[PHP-DOC] cvs: phpdoc /howto phpdoc-howto.ent phpdoc-howto.xml From: Daniel Beckham (danbeck <email protected>)
Date: 09/05/00

danbeck Tue Sep 5 15:16:20 2000 EDT

  Modified files:
    /phpdoc/howto phpdoc-howto.ent phpdoc-howto.xml
  Log:
  continued drafting the documentation, added a few new entities
  
Index: phpdoc/howto/phpdoc-howto.ent
diff -u phpdoc/howto/phpdoc-howto.ent:1.1 phpdoc/howto/phpdoc-howto.ent:1.2
--- phpdoc/howto/phpdoc-howto.ent:1.1 Fri Sep 1 14:21:01 2000
+++ phpdoc/howto/phpdoc-howto.ent Tue Sep 5 15:16:19 2000
@@ -4,6 +4,11 @@
 <!ENTITY email.danbeck "danbeck <email protected>">
 <!ENTITY email.group.php "group <email protected>">
 
+<!ENTITY url.php "http://www.php.net/">
+<!ENTITY url.php.manual "http://www.php.net/manual/">
+<!ENTITY url.php.manual.plain "http://www.php.net/manual/html/">
+<!ENTITY url.php.manual.pdf "http://www.php.net/distributions/manual.pdf">
+<!ENTITY url.php.manual.rtf "http://www.php.net/distributions/manual.rtf">
 <!ENTITY url.cvs "http://www.cvshome.org/">
 <!ENTITY url.docbookdtd "http://www.oasis-open.org/docbook/">
 <!ENTITY url.nwalsh "http://nwalsh.com/docbook/dsssl/">
Index: phpdoc/howto/phpdoc-howto.xml
diff -u phpdoc/howto/phpdoc-howto.xml:1.2 phpdoc/howto/phpdoc-howto.xml:1.3
--- phpdoc/howto/phpdoc-howto.xml:1.2 Fri Sep 1 14:21:01 2000
+++ phpdoc/howto/phpdoc-howto.xml Tue Sep 5 15:16:19 2000
@@ -258,7 +258,7 @@
    <para>
     <informalexample>
      <programlisting>
-rpm -Uvh *.rpm
+$ rpm -Uvh *.rpm
      </programlisting>
     </informalexample>
    </para>
@@ -267,12 +267,12 @@
     Or, you can issue them one by one in the following order:
     <informalexample>
      <programlisting>
-rpm -Uvh docbook-3.x-5.src.rpm
-rpm -Uvh jade-1.2.x-4.src.rpm
-rpm -Uvh jadetex-2.x-0.src.rpm
-rpm -Uvh psgml-1.2.x-1.src.rpm
-rpm -Uvh sgml-common-0.1-3.src.rpm
-rpm -Uvh stylesheets-0.10-2.src.rpm
+$ rpm -Uvh docbook-3.x-5.src.rpm
+$ rpm -Uvh jade-1.2.x-4.src.rpm
+$ rpm -Uvh jadetex-2.x-0.src.rpm
+$ rpm -Uvh psgml-1.2.x-1.src.rpm
+$ rpm -Uvh sgml-common-0.1-3.src.rpm
+$ rpm -Uvh stylesheets-0.10-2.src.rpm
      </programlisting>
     </informalexample>
    </para>
@@ -394,7 +394,7 @@
     specify the repository's cvsroot directory like this:
     <informalexample>
      <programlisting>
-cvs -d :pserver:<parameter>username</parameter> <email protected>:/repository checkout <parameter>phpdoc</parameter>
+$ cvs -d :pserver:<parameter>username</parameter> <email protected>:/repository checkout <parameter>phpdoc</parameter>
      </programlisting>
     </informalexample>
    </para>
@@ -441,7 +441,7 @@
     login to the CVS repository. Issue the following command:
     <informalexample>
      <programlisting>
-cvs login
+$ cvs login
      </programlisting>
     </informalexample>
    </para>
@@ -452,7 +452,7 @@
     remap="tt">cvsroot</literal>:
     <informalexample>
      <programlisting>
-cvs -d :pserver:<parameter>username</parameter> <email protected>:/repository login
+$ cvs -d :pserver:<parameter>username</parameter> <email protected>:/repository login
      </programlisting>
     </informalexample>
    </para>
@@ -484,7 +484,7 @@
     there. Issue the following command:
     <informalexample>
      <programlisting>
-cvs checkout <parameter>phpdoc</parameter>
+$ cvs checkout <parameter>phpdoc</parameter>
      </programlisting>
     </informalexample>
    </para>
@@ -513,7 +513,7 @@
     command:
     <informalexample>
      <programlisting>
-cvs update
+$ cvs update
      </programlisting>
     </informalexample>
    </para>
@@ -524,7 +524,7 @@
     update command:
     <informalexample>
      <programlisting>
-cvs update <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
+$ cvs update <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
      </programlisting>
     </informalexample>
    </para>
@@ -535,7 +535,7 @@
     the filenames:
     <informalexample>
      <programlisting>
-cvs update <parameter>en/functions/file1</parameter> <optional><parameter>en/chapters/file2</parameter></optional>
+$ cvs update <parameter>en/functions/file1</parameter> <optional><parameter>en/chapters/file2</parameter></optional>
      </programlisting>
     </informalexample>
    </para>
@@ -557,7 +557,7 @@
     following command:
     <informalexample>
      <programlisting>
-cvs status -l
+$ cvs status -l
      </programlisting>
     </informalexample>
    </para>
@@ -568,7 +568,7 @@
     specific filenames to check the status of:
     <informalexample>
      <programlisting>
-cvs status <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
+$ cvs status <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
      </programlisting>
     </informalexample>
    </para>
@@ -612,7 +612,7 @@
     To commit a file, issue the following command:
     <informalexample>
      <programlisting>
-cvs commit -m 'added new blah() function' <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
+$ cvs commit -m 'added new blah() function' <parameter>file1</parameter> <optional><parameter>file2</parameter></optional>
      </programlisting>
     </informalexample>
    </para>
@@ -643,33 +643,39 @@
    <para>
     The <filename>Makefile</filename> controls serveral aspects of how
     documenation is validated and created. To generate a
- <filename>Makefile</filename>, <command>cd</command> to the
- <filename>phpdoc</filename> directory and issue the following
- commands:
+ <filename>Makefile</filename> from a fresh checkout,
+ <command>cd</command> to the <filename>phpdoc</filename> directory
+ and issue the following commands:
     <informalexample>
      <programlisting>
-autoconf
+$ autoconf
 
-./configure
+$ ./configure
      </programlisting>
     </informalexample>
     This will generate a current <filename>Makefile</filename> for
     your copy of the <emphasis>phpdoc</emphasis> tree.
    </para>
 
+ </sect2>
+
+
+ <sect2 id="validating-changes">
+ <title>Validating Changes</title>
+
    <para>
     Now that you have a Makefile, you can test the changes you have
     made:
     <informalexample>
      <programlisting>
-cd phpdoc
-make test
+$ cd phpdoc
+$ make test
      </programlisting>
     </informalexample>
    </para>
 
    <para>
- This will generate output similar to this:
+ Which will generate something like this:
    </para>
    <para>
     <screen>
@@ -678,10 +684,108 @@
 creating manual.xml
 nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
     </screen>
- If there weren't any mistakes. =)
    </para>
 
+ <para>
+ If you made a mistake such as forgetting to close a tag or using
+ an invalid tag name, <command>make test</command> will report the
+ error and give you the line number it found it at.
+ </para>
+ <para>
+ <screen>
+touch .manual.xml
+CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
+creating manual.xml
+nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
+nsgmls:en/functions/strings.xml:54:13:E: end tag for "para" omitted, but OMITTAG NO was specified
+make: *** [test] Error 1
+ </screen>
+ </para>
+ <para>
+ In the above example output, the parser expected to see an end tag
+ for &lt;para&gt; at line 54 in the file en/functions/strings.xml.
+ Using this information, you can go back to the file and correct
+ the mistake before committing your changes.
+ </para>
+
+ </sect2>
+
+
+ <sect2 id="viewing-your-changes">
+ <title>Viewing Your Changes</title>
+
+ <para>
+ There are several stylesheets available for generating viewable
+ documenation, the most useful will probably be:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal remap="tt">html</literal>, the plain html manual found at <ulink
+ url="&url.php.manual.plain">&url.php.manual.plain</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal remap="tt">phpweb</literal>, the main PHP online manual found at <ulink
+ url="&url.php.manual">&url.php.manual</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal remap="tt">pdf</literal>, a PDF version of the manual found at <ulink
+ url="&url.php.manual.pdf">&url.php.manual.pdf</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal remap="tt">rtf</literal>, a RTF (Rich Text Format) version of the manual found at
+ <ulink url="&url.php.manual.rtf">&url.php.manual.rtf</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+<!-- 7:31, html generation time for Athalon 700 -->
+
+ <para>
+ To generate a viewable copy of the documenation,
+ <command>cd</command> to the <filename>phpdoc</filename> directory
+ and issue one of the following commands:
+ <informalexample>
+ <programlisting>
+$ make html
+$ make phpweb
+$ make pdf
+$ make rtf
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <note>
+ <para>
+ Generating viewable documentation is CPU intensive and can take a
+ little while to complete. e.g. It takes about 7m 30s on a 700MHz
+ box I'm using to write this documentation on.
+ </para>
+ </note>
+
+ <para>
+ If all goes well, you should have your own copy of the
+ documentation, including any changes you've made.
+ </para>
+
   </sect2>
+
+
+ <sect2 id="function-lists">
+ <title>Creating Documented/Undocumented Function Lists</title>
+
+ <para>
+
+ </para>
+
+ </sect2>
+
 
  </sect1>