GENERAL:

Examples need to be clear and simple, but should
show the possibilities and usage of the function[s]
used. Only use OOP features where you would like to
present them, use simple functions in other areas.

Do not take advantage of register_globals, just in
case you would like to present what register_globals
means.

Make sure that the code won't produce any warnings
even with error_reporting = E_ALL.


HOWTO ADD EXAMPLES TO THE DOCS:

1. Add PHP example code programlistings always with a role attribute set to
   "php". Never add any other programlisting or PHP output with such a
   role. It is reserved for PHP source code only. This role is used to
   detect PHP code and highlight:
   <programlisting role="php">

2. Title of examples: where appropriate use the function in the title,
  e.g.: <title><function>array</function> example</title>

3. The contents of examples with programlistings start on column 0 in the
   XML code.

4. All examples use the <?php ... ?> form instead of <? ... ?>. Use
   <![CDATA[... ]]> for examples, since it eliminates the need to change <
   to &lt;,etc. Examples look much better, and are easily manageable.

5. Deprecated aliases and syntax should not be used in examples.

6. If an example uses arguments specific to a newer version of PHP, it is
   helpful to note this in the example: 
   foo("bar", "baz"); // second argument was added in PHP 4.0.3

   If you use new vars (like $_ENV), always note that
   from when they are available, and what to use in older
   versions (always show newer and better examples too
   by the side of older ones)

7. The language constants true, false and null should be written as &true;,
   &false; and &null;. In Examples write TRUE, FALSE, NULL.

8. Never use tabs, not even in example program listings. XML should be
   indented with one space character for each level of indentation; example
   code uses four spaces.

9. Keep in mimd: In <![CDATA[... ]]> sections nothing is parsed. So be sure
   to put XML-code that needs parsing outside of CDATA sections, e.g.
   dev-comments or links. Do not use any entities like &lt;.


ERROR HANDLING

more to come???

Proper error handling, "... or die(...);" is good for development, 
but useless for production.
Use some user defined exit function instead on error.
example: 
$conn = mysql_connect($host, $user, $pass)
if (!$conn) {
    doSomething();
    echo 'output stuff';
    exit;
}


ABOUT VARIABLES/CONSTANTS/STRINGS:

1. Don't use variable which are not set in examples.

2. Constants should always be all-uppercase.

3. Use single qoutes ' where no metachars or variables need to be parsed.

4. For output use echo, where adequate.

5. Lowercase html-tags.

6. Variables in Strings

in discussion:

echo "bar is $bar";
vs.
echo 'bar is '.$bar;

What about ${} and {$}???

echo "this is ${bar}";
echo "this is {$bar}";
Hmm :)  Variable variables come to mind but then again ${$var} can be seen
as a mix of both :)

That is something indicates, why both works, and should work, and
why ${varname[1]} should not. But it works as you reported... Hm...


use ${varname} for complex vars in strings, $varname[x]
will confuse readers, as this is illegal outside strings,
concatenation makes code unreadable

arrays in strings:
   "a $arr[foo] b"
   "a {$arr['foo']} b"
   'a ' . $arr['foo'] . ' b';



HOWTO WRITE...

A: CONTROL STRUCTURES

These include if, for, while, switch, etc. Here is an example if statement,
since it is the most complicated of them:
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}

Control statements should have one space between the control keyword and
opening parenthesis, to distinguish them from function calls.

You are strongly encouraged to always use curly braces even in situations
where they are technically optional. Having them increases readability and
decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;

}


B: FUNCTIONS:

1. FUNCTION NAMING:

Function names should always be all-lowercase.????
If you need more than one word use foo_function() in functions defined in examples.


2. FUNCTION CALLS

Functions should be called with no spaces between the function name, the
opening parenthesis, and the first parameter; spaces between commas and each
parameter, and no space between the last
parameter, the closing parenthesis, and the semicolon. Here's an example:
$var = foo($bar, $baz, $quux);

As displayed above, there should be one space on either side of an equals
sign used to assign the
return value of a function to a variable. In the case of a block of related
assignments, more space
may be inserted to promote readability:
$short         = foo($bar);
$long_variable = foo($baz);

3. FUNCTION DEFINITIONS

Function declaractions follow the "one true brace" convention:
function foo_function($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}

Arguments with default values go at the end of the argument list.
Always attempt to return a meaningful value from a function if one is
appropriate. Here is a slightly longer example:
function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}


C: COMMENTS

C style comments (/* */) and standard C++ comments (//) are both fine.
Use of Perl/shell style comments (#) is discouraged.
Do not use phpdoc (PEAR) comments, like @param.

Suggestion: for single line comments use //, it seems to be more readable
to me than /* */

D: EXAMPLE URLS/EMAIL

Use "example.com" for all example URLs, per RFC 2606.
Use sample email-adresses like joe@example.com
(someone pointed out the many junk mail coming
to birthdaygift@php.net and the like caused by an
example on the mail function page).


E: EXAMPLE PRINTOUTS

For short example printouts, use a C++ style comment
on the line where the output occurs, or the next line,
where it is needed:
echo $var; // outputs: 32

For longer example printouts use the screen
container in conjunction with <![CDATA[... ]]>:
     <para>
      This example would display:
      <screen>
<![CDATA[
a = orange
d = lemon
b = banana
c = apple
]]>
      </screen>
     </para>



COMPLETE EXAMPLE SKELETON

The screen section is optional.

    <para>
     <example>
      <title><function></function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
your example code here
...
?>
]]>
      </programlisting>
      <para>
       The above example would produce the following output:
       <screen>
<![CDATA[
your long example output here
...
]]>
       </screen>
      </para>
     </example>
    </para>