[PHP-DOC] cvs: phpdoc /howto working.xml

[Derick Rethans]

derick          Fri Jun 20 11:05:56 2003 EDT

  Modified files:              
    /phpdoc/howto       working.xml 
  Log:
  - Adding some guidelines to the Howto
  #- I know this isn't discussed yet, but if there are objects we can discuss
  #  those at the meeting
  
  
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.32 phpdoc/howto/working.xml:1.33
--- phpdoc/howto/working.xml:1.32       Thu Jun 19 16:23:18 2003
+++ phpdoc/howto/working.xml    Fri Jun 20 11:05:56 2003
@@ -160,6 +160,7 @@
     <listitem><simpara>
      Deprecated aliases and syntax should not be used in examples.
     </simpara></listitem>
+
     <listitem><para>
      If an example uses arguments specific to a newer version of
      PHP, it is helpful to note this in the example:
@@ -167,7 +168,7 @@
 foo("bar", "baz"); // second argument was added in PHP 4.0.3
      </programlisting>
      New arguments are denoted in the main text of the
-     entry using the form
+     entry using the form:
      <programlisting>
 <![CDATA[
 <note>
@@ -177,7 +178,30 @@
 </note>
 ]]>
       </programlisting>
+      Make sure note elements are always children of the main element in a
+      file, unless the note belongs to a specific item in the text, such as an
+      example:
+     <programlisting>
+<![CDATA[
+  <para>
+   <example>
+    <title />
+    <programlisting/>
+    <para>
+     The output is:
+    </para>
+    <screen />
+   </example>
+   <note>
+    <simpara>
+     This example only works on Unices.
+    </simpara>
+   </note>
+  </para>
+]]>
+      </programlisting>
     </para></listitem>
+
     <listitem><simpara>
      The language constants true, false and null
      should be written as <literal>&amp;true;</literal>,
@@ -277,6 +301,32 @@
      &lt;function>realfunc&lt;/function></literal>.
      This way, people can go to realfunc
      straight from the <literal>ref.foo</literal> page.
+    </simpara></listitem>
+
+    <listitem><simpara>
+     Document examples always with the following structure:
+     <programlisting role="xml">
+&lt;para&gt;
+ &lt;example&gt;
+  &lt;title /&gt;
+  &lt;programlisting&gt;
+&lt;![CDATA[
+&lt;?php
+echo "foo\n";
+?&gt;
+]]&gt;
+  &lt;/programlisting&gt;
+  &lt;para&gt;
+   The output is:
+  &lt;/para&gt;
+  &lt;screen&gt;
+&lt;![CDATA[
+foo
+]]&gt;
+  &lt;/screen&gt;
+ &lt;/example&gt;
+&lt;/para&gt;
+     </programlisting>
     </simpara></listitem>
    </orderedlist>
   </para>



-- 
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php