cvs: phpdoc /howto working.xml
| From: | Philip Olson | Date: | Wed, 22 Sep 2004 21:09:24 +0000 |
| Subject: | cvs: phpdoc /howto working.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969364240@lists.php.net to get a copy of this message | ||
philip Wed Sep 22 17:09:24 2004 EDT
Modified files:
/phpdoc/howto working.xml
Log:
Added new doc skeletons for ini.xml configure.xml constants.xml reference.xml and func-name.xml
http://cvs.php.net/diff.php/phpdoc/howto/working.xml?r1=1.46&r2=1.47&ty=u Index: phpdoc/howto/working.xml diff -u phpdoc/howto/working.xml:1.46 phpdoc/howto/working.xml:1.47 --- phpdoc/howto/working.xml:1.46 Fri Sep 3 05:13:39 2004 +++ phpdoc/howto/working.xml Wed Sep 22 17:09:24 2004 @@ -465,22 +465,153 @@ <chapter id="chapter-skeletons"> <title>Documentation Skeletons</title> - <para> - Below are some "skeletons" to copy and paste from when adding - documentation. + Below are some "skeletons" to copy and paste from when adding + documentation. All of these files should end with a line ending ("\n"). If + a section does not exist (like a ChangeLog), simply don't include that + refsect1 inside the documentation. </para> + <note> + <para> + The documentation skeletons below are new, from around August of 2004. + </para> + </note> <para> <example> - <title>Function reference file in lang/reference/EXTNAME/functions</title> - <programlisting> -<![CDATA[ - <reference> - <title></title> - <titleabbrev></titleabbrev> + <title>A function skeleton (<filename>func-name.xml</filename>)</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<refentry id="function.func-name"> + <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>int</type><parameter>firstparameter</parameter></methodparam> + <!-- Example: Optional parameter --> + <methodparam choice="opt"><type>string</type><parameter>secondparameter</parameter></methodparam> + <!-- Example: Passed by reference --> + <methodparam><type>bool</type><parameter role="reference">thirdparameter</parameter></methodparam> + <!-- Example: If no methodparams exist (void), use this --> + <void /> + </methodsynopsis> + <para> + The functions 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> + <varlistentry> + <term><parameter>thirdparameter</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="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>Write the PHP version here (Ex. 4.3.0)</entry> + <entry> + Describe the change + </entry> + </row> + <row> + <entry>...</entry> + <entry> + ... + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>functionname</function> example</title> + <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="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> - </reference> -<!-- Keep this comment at the end of the file +<!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t @@ -499,256 +630,220 @@ vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> -]]> +--> + </programlisting> </example> </para> - <para> <example> - <title>Function reference entry</title> - <programlisting> - <refentry id="function."> - <refnamediv> - <refname></refname> - <refpurpose></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>RETURNTYPE</type> <methodname>FUNCTIONNAME</methodname> - <methodparam><type>ARGTYPE1</type> <parameter>ARGNAME1</parameter></methodparam> - <methodparam><type>ARGTYPE2</type> <parameter>ARGNAME2</parameter></methodparam> - <!-- optional parameter --> - <methodparam choice='opt'> - <type>ARGTYPE3</type> <parameter>ARGNAME3</parameter> - </methodparam> - <!-- optional parameter with default value, choice='opt' is default in this case --> - <methodparam> - <type>ARGTYPE3</type> - <parameter>ARGNAME3</parameter> - <initializer>default-value</initializter> - </methodparam> - <!-- use <void /> if you have no parameters at all --> - </methodsynopsis> - <simpara> - A simple paragraph that can not contain anything that requires - fancy layout. - </simpara> - <para> - A normal paragraph that can contain lots of stuff. For example - <example> - <title>Code examples</title> - <programlisting role="php"> -<![CDATA[ + <title>A <filename>reference.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<reference id="ref.extname"> + <title>Extname &Functions;</title> + <titleabbrev>Extname</titleabbrev> + + <partintro> + <section id="extname.intro"> + &reftitle.intro; + <para> + + </para> + </section> -/* Use a role="php" only for PHP codes. See <screen> - * and other DocBook elements to express other - * types of listings. Use other role attributes for - * other type of programlistings, like: sql, httpd, ini, - * shell or http, as dictated by the example type. - */ - -/* Do all indentation with spaces, not tabs, just to be sure. - * Don't try pushing the code to the right by adding spaces in - * front, this is the style sheet's job. - */ - -// a function example -function some_code($foo) -{ - // use four spaces of indentation -} + <section id="extname.requirements"> + &reftitle.required; + <para> + + </para> + </section> -// an example of bracket usage and spacing, always use -// brackets, even when they are physically not needed -if (some_code($foo) == "foo") { - echo "foo"; -} elseif (some_code($foo) == "bar") { - echo "bar"; -} else { - echo "No foo, no bar"; -} + &reference.extname.configure; + &reference.extname.ini; -]]> - </programlisting> - </example> + <section id="extname.resources"> + &reftitle.resources; + &no.resource; + </section> - The text in a paragraph may continue after the example as well. - Here is how to make lists: + &reference.extname.constants; + </partintro> - <itemizedlist> - <listitem> - <simpara> - List items must contain a container element such as - simpara or para (there are plenty of others too, see the - DocBook reference for the listitem element). - </simpara> - </listitem> - - <listitem> - <simpara> - List items must contain simple paragraphs or paragraphs. - </simpara> - </listitem> - </itemizedlist> - - <itemizedlist> - <listitem> - <para> - If you plan on making sub-lists, you must use para - <orderedlist> - <listitem><simpara> first list item</simpara></listitem> - <listitem><simpara> second list item</simpara></listitem> - </orderedlist> - You can also continue an ordered list you just left off - <orderedlist> - <listitem><simpara> third list item</simpara></listitem> - <listitem><simpara> fourth list item</simpara></listitem> - </orderedlist> - </para> - </listitem> - </itemizedlist> + &reference.extname.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 +--> - </para> - <simpara> - The documentation for a function should be wrapped up with - a "See also" list like this: - </simpara> - <simpara> - See also <function>stripslashes</function> and - <function>quotemeta</function>. - </simpara> - </refsect1> - </refentry> </programlisting> </example> </para> <para> - For parts we have no skeleton here, please look at existing files in the - <filename>phpdoc</filename> CVS module. If you are not sure a specific file - is good for a start, please ask on the <link linkend="chapter-maillist">phpdoc - mailing list</link>. If you have any suggestions for more skeletons do not - hesitate. + There are several PECL related entities inside of + <filename>language-snippets.ent</filename>. Be sure to include information + on where Windows users can find the DLL. + <example> + <title>A <filename>configure.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<section id="extname.installation"> + &reftitle.install; + <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 +--> + + </programlisting> + </example> </para> <para> - And we're introducing a new doc skeleton where multiple refsect1's are - used, as well as a lot more entities. Names in ALLCAPS would be changed - so for example RETURNTYPE would instead be bool, string, etc. Here's a - draft using example_func() as an example. <emphasis>Do not implement this - style yet!</emphasis> There are also reftitles for classes, constructors, - and methods. An OOP doc skeleton will be written in the future. - reftitles are located in <filename>language-defs.ent</filename>. + <example> + <title>A <filename>constants.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<section id="extname.constants"> + &reftitle.constants; + &extension.constants; + <para> + <variablelist> + <varlistentry> + <term> + <constant>CONSTANT_NAME</constant> + (<type>itstype</type>) + </term> + <listitem> + <simpara> + + </simpara> + </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 +--> + + </programlisting> + </example> </para> <para> <example> - <title>An example example using refsect1's and reftitle entities</title> - <programlisting> -<refentry id="function.example-func"> - <refnamediv> - <refname>example_func</refname> - <refpurpose>Displays how to write a function man page, no ending period here</refpurpose> - </refnamediv> - <refsect1> - &reftitle.description; - <methodsynopsis> - <type>RETURNTYPE</type><methodname>example_func</methodname> - <methodparam><type>ARGTYPE1</type><parameter>ARGNAME1</parameter></methodparam> - <methodparam><type>ARGTYPE2</type><parameter>ARGNAME2</parameter></methodparam> - <!-- parameter takes on a referenced variable --> - <methodparam><type>ARGTYPE2</type><parameter>&amp;ARGNAME2</parameter></methodparam> - <!-- optional parameter --> - <methodparam choice='opt'><type>ARGTYPE3</type><parameter>ARGNAME3</parameter></methodparam> - <!-- optional parameter with default value, choice='opt' is default in this case --> - <methodparam> - <type>ARGTYPE3</type> - <parameter>ARGNAME3</parameter> - <initializer>DEFAULTVALUE</initializter> - </methodparam> - <!-- Or, use <void /> if the function has no parameters at all --> - </methodsynopsis> - <simpara> - We are still in the description section. The description includes - information about the function, like what it does. This document is no - more than 78 characters in width except for the methodsynopsis. No tabs! - And only use unix-style line endings. - </simpara> - <para> - To continue on with our description we document parameter changes although - this may have it's own section in the near future. - </para> - </refsect1> + <title>A <filename>ini.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<section id="extname.configuration"> + &reftitle.runtime; + &extension.runtime; + <para> + <table> + <title>Extname &ConfigureOptions;</title> + <tgroup cols="3"> + <thead> + <row> + <entry>&Name;</entry> + <entry>&Default;</entry> + <entry>&Changable;</entry> + </row> + </thead> + <tbody> + <row> + <entry>theini_option</entry> + <entry>itsvalue</entry> + <entry>its PHP_INI_* value</entry> + </row> + </tbody> + </tgroup> + </table> - <refsect1> - &reftitle.returnvalues; - <simpara> - This section describes return values. If the function simply returns - TRUE on success and FALSE on failure, simply use the &return.success; - entity here (this entity does not contain it's own para) otherwise describe - what the function returns in all cases. Also, there are &true; and - &false; entities. - </simpara> - </refsect1> - - <refsect1> - &reftitle.examples; - <para> - Words may go here, but most likely not. Your example must meet the PEAR - Coding standards. - <example> - <title>An <function>example_func<function>example</title> - <programlisting role="php"> -<![CDATA[ -<?php -/* Use a role="php" only for PHP codes. See <screen> - * and other DocBook elements to express other - * types of listings. Use other role attributes for - * other type of programlistings, like: sql, httpd, ini, - * shell or http, as dictated by the example type. - */ - -/* Do all indentation with spaces, not tabs, just to be sure. - * Don't try pushing the code to the right by adding spaces in - * front, this is the style sheet's job. - * - * All examples must meet the PEAR Coding Standard - */ + &php_ini_constants; + </para> -// a function example -function some_code($foo) -{ - // use four spaces of indentation -} - -// an example of bracket usage and spacing, always use -// brackets, even when they are physically not needed -if (some_code($foo) == 'foo') { - echo 'foo'; -} elseif (some_code($foo) == 'bar') { - echo 'bar'; -} else { - echo 'No foo, no bar'; -} -?> -]]> - </programlisting> - </example> - Words may go here, but most likely not. Notice the use of the &listendand; - entity below, and how the functions are listed as one function per line. - There are no ending periods for see also's (or are there?). - </para> - </refsect1> - - <refsect1> - &reftitle.seealso; - <simpara> - <function>somefunc</function>, - <function>someother_func</function>&listendand; - <function>yetanotherfunc</function> - </simpara> - </refsect1> -</refentry> + &ini.descriptions.title; + + <para> + <variablelist> + <varlistentry id="ini.extname.theini-option"> + <term> + <parameter>theini_option</parameter> + <type>thetype</type> + </term> + <listitem> + <para> + + </para> + </listitem> + </varlistentry> + </variablelist> + </para> +</section> <!-- Keep this comment at the end of the file Local variables: @@ -761,7 +856,7 @@ sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil -sgml-default-dtd-file:"../../../../manual.ced" +sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil @@ -770,15 +865,9 @@ vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> + </programlisting> </example> - </para> - <para> - For parts we have no skeleton here, please look at existing files in the - <filename>phpdoc</filename> CVS module. If you are not sure a specific file - is good for a start, please ask on the <link linkend="chapter-maillist">phpdoc - mailing list</link>. If you have any suggestions for more skeletons do not - hesitate. </para> </chapter>
http://cvs.php.net/diff.php/phpdoc/howto/working.xml?r1=1.46&r2=1.47&ty=u Index: phpdoc/howto/working.xml diff -u phpdoc/howto/working.xml:1.46 phpdoc/howto/working.xml:1.47 --- phpdoc/howto/working.xml:1.46 Fri Sep 3 05:13:39 2004 +++ phpdoc/howto/working.xml Wed Sep 22 17:09:24 2004 @@ -465,22 +465,153 @@ <chapter id="chapter-skeletons"> <title>Documentation Skeletons</title> - <para> - Below are some "skeletons" to copy and paste from when adding - documentation. + Below are some "skeletons" to copy and paste from when adding + documentation. All of these files should end with a line ending ("\n"). If + a section does not exist (like a ChangeLog), simply don't include that + refsect1 inside the documentation. </para> + <note> + <para> + The documentation skeletons below are new, from around August of 2004. + </para> + </note> <para> <example> - <title>Function reference file in lang/reference/EXTNAME/functions</title> - <programlisting> -<![CDATA[ - <reference> - <title></title> - <titleabbrev></titleabbrev> + <title>A function skeleton (<filename>func-name.xml</filename>)</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<refentry id="function.func-name"> + <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>int</type><parameter>firstparameter</parameter></methodparam> + <!-- Example: Optional parameter --> + <methodparam choice="opt"><type>string</type><parameter>secondparameter</parameter></methodparam> + <!-- Example: Passed by reference --> + <methodparam><type>bool</type><parameter role="reference">thirdparameter</parameter></methodparam> + <!-- Example: If no methodparams exist (void), use this --> + <void /> + </methodsynopsis> + <para> + The functions 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> + <varlistentry> + <term><parameter>thirdparameter</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="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>Write the PHP version here (Ex. 4.3.0)</entry> + <entry> + Describe the change + </entry> + </row> + <row> + <entry>...</entry> + <entry> + ... + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>functionname</function> example</title> + <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="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> - </reference> -<!-- Keep this comment at the end of the file +<!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t @@ -499,256 +630,220 @@ vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> -]]> +--> + </programlisting> </example> </para> - <para> <example> - <title>Function reference entry</title> - <programlisting> - <refentry id="function."> - <refnamediv> - <refname></refname> - <refpurpose></refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>RETURNTYPE</type> <methodname>FUNCTIONNAME</methodname> - <methodparam><type>ARGTYPE1</type> <parameter>ARGNAME1</parameter></methodparam> - <methodparam><type>ARGTYPE2</type> <parameter>ARGNAME2</parameter></methodparam> - <!-- optional parameter --> - <methodparam choice='opt'> - <type>ARGTYPE3</type> <parameter>ARGNAME3</parameter> - </methodparam> - <!-- optional parameter with default value, choice='opt' is default in this case --> - <methodparam> - <type>ARGTYPE3</type> - <parameter>ARGNAME3</parameter> - <initializer>default-value</initializter> - </methodparam> - <!-- use <void /> if you have no parameters at all --> - </methodsynopsis> - <simpara> - A simple paragraph that can not contain anything that requires - fancy layout. - </simpara> - <para> - A normal paragraph that can contain lots of stuff. For example - <example> - <title>Code examples</title> - <programlisting role="php"> -<![CDATA[ + <title>A <filename>reference.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<reference id="ref.extname"> + <title>Extname &Functions;</title> + <titleabbrev>Extname</titleabbrev> + + <partintro> + <section id="extname.intro"> + &reftitle.intro; + <para> + + </para> + </section> -/* Use a role="php" only for PHP codes. See <screen> - * and other DocBook elements to express other - * types of listings. Use other role attributes for - * other type of programlistings, like: sql, httpd, ini, - * shell or http, as dictated by the example type. - */ - -/* Do all indentation with spaces, not tabs, just to be sure. - * Don't try pushing the code to the right by adding spaces in - * front, this is the style sheet's job. - */ - -// a function example -function some_code($foo) -{ - // use four spaces of indentation -} + <section id="extname.requirements"> + &reftitle.required; + <para> + + </para> + </section> -// an example of bracket usage and spacing, always use -// brackets, even when they are physically not needed -if (some_code($foo) == "foo") { - echo "foo"; -} elseif (some_code($foo) == "bar") { - echo "bar"; -} else { - echo "No foo, no bar"; -} + &reference.extname.configure; + &reference.extname.ini; -]]> - </programlisting> - </example> + <section id="extname.resources"> + &reftitle.resources; + &no.resource; + </section> - The text in a paragraph may continue after the example as well. - Here is how to make lists: + &reference.extname.constants; + </partintro> - <itemizedlist> - <listitem> - <simpara> - List items must contain a container element such as - simpara or para (there are plenty of others too, see the - DocBook reference for the listitem element). - </simpara> - </listitem> - - <listitem> - <simpara> - List items must contain simple paragraphs or paragraphs. - </simpara> - </listitem> - </itemizedlist> - - <itemizedlist> - <listitem> - <para> - If you plan on making sub-lists, you must use para - <orderedlist> - <listitem><simpara> first list item</simpara></listitem> - <listitem><simpara> second list item</simpara></listitem> - </orderedlist> - You can also continue an ordered list you just left off - <orderedlist> - <listitem><simpara> third list item</simpara></listitem> - <listitem><simpara> fourth list item</simpara></listitem> - </orderedlist> - </para> - </listitem> - </itemizedlist> + &reference.extname.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 +--> - </para> - <simpara> - The documentation for a function should be wrapped up with - a "See also" list like this: - </simpara> - <simpara> - See also <function>stripslashes</function> and - <function>quotemeta</function>. - </simpara> - </refsect1> - </refentry> </programlisting> </example> </para> <para> - For parts we have no skeleton here, please look at existing files in the - <filename>phpdoc</filename> CVS module. If you are not sure a specific file - is good for a start, please ask on the <link linkend="chapter-maillist">phpdoc - mailing list</link>. If you have any suggestions for more skeletons do not - hesitate. + There are several PECL related entities inside of + <filename>language-snippets.ent</filename>. Be sure to include information + on where Windows users can find the DLL. + <example> + <title>A <filename>configure.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<section id="extname.installation"> + &reftitle.install; + <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 +--> + + </programlisting> + </example> </para> <para> - And we're introducing a new doc skeleton where multiple refsect1's are - used, as well as a lot more entities. Names in ALLCAPS would be changed - so for example RETURNTYPE would instead be bool, string, etc. Here's a - draft using example_func() as an example. <emphasis>Do not implement this - style yet!</emphasis> There are also reftitles for classes, constructors, - and methods. An OOP doc skeleton will be written in the future. - reftitles are located in <filename>language-defs.ent</filename>. + <example> + <title>A <filename>constants.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<section id="extname.constants"> + &reftitle.constants; + &extension.constants; + <para> + <variablelist> + <varlistentry> + <term> + <constant>CONSTANT_NAME</constant> + (<type>itstype</type>) + </term> + <listitem> + <simpara> + + </simpara> + </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 +--> + + </programlisting> + </example> </para> <para> <example> - <title>An example example using refsect1's and reftitle entities</title> - <programlisting> -<refentry id="function.example-func"> - <refnamediv> - <refname>example_func</refname> - <refpurpose>Displays how to write a function man page, no ending period here</refpurpose> - </refnamediv> - <refsect1> - &reftitle.description; - <methodsynopsis> - <type>RETURNTYPE</type><methodname>example_func</methodname> - <methodparam><type>ARGTYPE1</type><parameter>ARGNAME1</parameter></methodparam> - <methodparam><type>ARGTYPE2</type><parameter>ARGNAME2</parameter></methodparam> - <!-- parameter takes on a referenced variable --> - <methodparam><type>ARGTYPE2</type><parameter>&amp;ARGNAME2</parameter></methodparam> - <!-- optional parameter --> - <methodparam choice='opt'><type>ARGTYPE3</type><parameter>ARGNAME3</parameter></methodparam> - <!-- optional parameter with default value, choice='opt' is default in this case --> - <methodparam> - <type>ARGTYPE3</type> - <parameter>ARGNAME3</parameter> - <initializer>DEFAULTVALUE</initializter> - </methodparam> - <!-- Or, use <void /> if the function has no parameters at all --> - </methodsynopsis> - <simpara> - We are still in the description section. The description includes - information about the function, like what it does. This document is no - more than 78 characters in width except for the methodsynopsis. No tabs! - And only use unix-style line endings. - </simpara> - <para> - To continue on with our description we document parameter changes although - this may have it's own section in the near future. - </para> - </refsect1> + <title>A <filename>ini.xml</filename> skeleton</title> + <programlisting role="xml"> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.47 $ --> +<section id="extname.configuration"> + &reftitle.runtime; + &extension.runtime; + <para> + <table> + <title>Extname &ConfigureOptions;</title> + <tgroup cols="3"> + <thead> + <row> + <entry>&Name;</entry> + <entry>&Default;</entry> + <entry>&Changable;</entry> + </row> + </thead> + <tbody> + <row> + <entry>theini_option</entry> + <entry>itsvalue</entry> + <entry>its PHP_INI_* value</entry> + </row> + </tbody> + </tgroup> + </table> - <refsect1> - &reftitle.returnvalues; - <simpara> - This section describes return values. If the function simply returns - TRUE on success and FALSE on failure, simply use the &return.success; - entity here (this entity does not contain it's own para) otherwise describe - what the function returns in all cases. Also, there are &true; and - &false; entities. - </simpara> - </refsect1> - - <refsect1> - &reftitle.examples; - <para> - Words may go here, but most likely not. Your example must meet the PEAR - Coding standards. - <example> - <title>An <function>example_func<function>example</title> - <programlisting role="php"> -<![CDATA[ -<?php -/* Use a role="php" only for PHP codes. See <screen> - * and other DocBook elements to express other - * types of listings. Use other role attributes for - * other type of programlistings, like: sql, httpd, ini, - * shell or http, as dictated by the example type. - */ - -/* Do all indentation with spaces, not tabs, just to be sure. - * Don't try pushing the code to the right by adding spaces in - * front, this is the style sheet's job. - * - * All examples must meet the PEAR Coding Standard - */ + &php_ini_constants; + </para> -// a function example -function some_code($foo) -{ - // use four spaces of indentation -} - -// an example of bracket usage and spacing, always use -// brackets, even when they are physically not needed -if (some_code($foo) == 'foo') { - echo 'foo'; -} elseif (some_code($foo) == 'bar') { - echo 'bar'; -} else { - echo 'No foo, no bar'; -} -?> -]]> - </programlisting> - </example> - Words may go here, but most likely not. Notice the use of the &listendand; - entity below, and how the functions are listed as one function per line. - There are no ending periods for see also's (or are there?). - </para> - </refsect1> - - <refsect1> - &reftitle.seealso; - <simpara> - <function>somefunc</function>, - <function>someother_func</function>&listendand; - <function>yetanotherfunc</function> - </simpara> - </refsect1> -</refentry> + &ini.descriptions.title; + + <para> + <variablelist> + <varlistentry id="ini.extname.theini-option"> + <term> + <parameter>theini_option</parameter> + <type>thetype</type> + </term> + <listitem> + <para> + + </para> + </listitem> + </varlistentry> + </variablelist> + </para> +</section> <!-- Keep this comment at the end of the file Local variables: @@ -761,7 +856,7 @@ sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil -sgml-default-dtd-file:"../../../../manual.ced" +sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil @@ -770,15 +865,9 @@ vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> + </programlisting> </example> - </para> - <para> - For parts we have no skeleton here, please look at existing files in the - <filename>phpdoc</filename> CVS module. If you are not sure a specific file - is good for a start, please ask on the <link linkend="chapter-maillist">phpdoc - mailing list</link>. If you have any suggestions for more skeletons do not - hesitate. </para> </chapter>