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>
