goba Sun Sep 23 09:24:17 2001 EDT
Modified files:
/phpdoc/howto howto.ent howto.xml
Log:
Incorporating more and more information in the howto.
Sorting the howto entities out. I would like to see
what is defined where :))
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.3 phpdoc/howto/howto.ent:1.4
--- phpdoc/howto/howto.ent:1.3 Sat Sep 8 16:50:26 2001
+++ phpdoc/howto/howto.ent Sun Sep 23 09:24:17 2001
@@ -1,35 +1,42 @@
<!--
- phpdoc-howto.ent: global entities for the phpdoc HOWTO
+ howto.ent: entities for the phpdoc HOWTO
-->
-<!ENTITY email.danbeck "[EMAIL PROTECTED]">
-<!ENTITY email.stig "[EMAIL PROTECTED]">
-<!ENTITY email.goba "[EMAIL PROTECTED]">
-<!ENTITY email.phpdoc "[EMAIL PROTECTED]">
+
+<!-- General email links -->
+<!ENTITY email.danbeck "[EMAIL PROTECTED]">
+<!ENTITY email.stig "[EMAIL PROTECTED]">
+<!ENTITY email.goba "[EMAIL PROTECTED]">
+<!ENTITY email.phpdoc "[EMAIL PROTECTED]">
<!ENTITY email.group.php "[EMAIL PROTECTED]">
-<!ENTITY url.php "http://www.php.net/";>
-<!ENTITY url.php.manual "http://www.php.net/manual/";>
+<!-- General PHP.net links -->
+<!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.php.manual.pdf "http://www.php.net/distributions/php_manual_en.pdf";>
+<!ENTITY url.php.manual.rtf "http://www.php.net/distributions/manual.rtf";>
+
+<!-- For DocBook section -->
+<!ENTITY url.docbook-dtd "http://www.oasis-open.org/docbook/";>
+<!ENTITY url.docbook-dtdref
+"http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html";>
+<!ENTITY url.docbook-intro
+"http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html";>
-<!ENTITY url.cvs "http://www.cvshome.org/";>
-<!ENTITY url.docbookdtd "http://www.oasis-open.org/docbook/";>
-<!ENTITY url.docbook-ref "http://www.ora.com/davenport/";>
-<!ENTITY url.docbook-dtdref "http://www.ora.com/homepages/dtdparse/docbook/3.0/";>
-<!ENTITY url.docbook-intro
"http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html";>
-
-<!ENTITY url.nwalsh "http://nwalsh.com/docbook/dsssl/";>
-<!ENTITY url.jade "http://www.jclark.com/jade/";>
-<!ENTITY url.dtdref "http://www.ora.com/homepages/dtdparse/docbook/3.0/";>
-<!ENTITY url.autoconf "http://sources.redhat.com/autoconf/";>
-<!ENTITY url.autoconf.ftp "ftp://ftp.gnu.org/gnu/autoconf/";>
-<!ENTITY url.rpm "http://www.rpm.org/";>
+<!-- For tools setup section -->
+<!ENTITY url.nwalsh "http://nwalsh.com/docbook/dsssl/";>
+<!ENTITY url.jade "http://www.jclark.com/jade/";>
+<!ENTITY url.autoconf "http://sources.redhat.com/autoconf/";>
+<!ENTITY url.autoconf.ftp "ftp://ftp.gnu.org/gnu/autoconf/";>
+<!ENTITY url.rpm "http://www.rpm.org/";>
<!ENTITY url.docbookmirror1
"ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/SRPMS/";>
<!ENTITY url.docbookmirror2
"ftp://sourceware.cygnus.com/pub/docbook-tools/docware/SRPMS/";>
-<!ENTITY url.cvstut1 "http://www.arc.unm.edu/~rsahu/cvs.html";>
-<!ENTITY url.cvstut2
"http://cellworks.washington.edu/pub/docs/cvs/tutorial/cvs_tutorial_1.html";>
-<!ENTITY url.cvs.php "http://cvs.php.net";>
+
+<!-- For CVS section -->
+<!ENTITY url.cvs "http://www.cvshome.org/";>
+<!ENTITY url.cvstut1 "http://www.arc.unm.edu/~rsahu/cvs.html";>
+<!ENTITY url.cvstut2
+"http://cellworks.washington.edu/pub/docs/cvs/tutorial/cvs_tutorial_1.html";>
+<!ENTITY url.cvs.php "http://cvs.php.net";>
<!ENTITY url.cvsaccount.php "http://www.php.net/cvs-php3.php";>
+
+<!-- For Misc section -->
<!ENTITY url.zend.phpfunc "http://www.zend.com/phpfunc/";>
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.4 phpdoc/howto/howto.xml:1.5
--- phpdoc/howto/howto.xml:1.4 Sat Sep 8 16:50:26 2001
+++ phpdoc/howto/howto.xml Sun Sep 23 09:24:17 2001
@@ -1,25 +1,16 @@
<?xml version='1.0' encoding='ISO-8859-1' ?>
-<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V1.7//EN"
- "../dbxml/docbookx.dtd" [
-<!ENTITY % global.entities SYSTEM "../global.ent">
-%global.entities;
+<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V1.7//EN"
+"../dbxml/docbookx.dtd" [
+
<!ENTITY % phpdoc-howto.entities SYSTEM "./howto.ent">
+<!ENTITY % global.entities SYSTEM "../global.ent">
+
%phpdoc-howto.entities;
+%global.entities;
]>
<article id="index">
-<!--
-
-MISC NOTES:
-
- ADD:
- Meta-q information
- Meta-Shift-^ information
-
- How to add a new section to the manual itself.
-
--->
+<!-- New Section: Authors - - - - - - - - - - - - - - - - - - - - - -->
<artheader>
<author>
@@ -52,20 +43,19 @@
<title>PHP Documentation HOWTO</title>
</artheader>
- <!-- Section1: intro -->
-
+<!-- New Section: About this document - - - - - - - - - - - - - - - -->
+
<sect1 id="about">
<title>About This Document</title>
-
+
<para>
This document contains information important for the PHP
- Documentation team members. When this document will be ready,
+ Documentation Group members. When this document will be ready,
you will find sections here about generating HTML documentation
from XML sources, adding new XML files, or using XSL style
sheets to process the source files.
</para>
- <!-- Section2: copyright -->
<sect2 id="copyright">
<title>Copyright Information</title>
@@ -78,9 +68,7 @@
<para>
This document may be reproduced and distributed in whole or in
part, in any medium physical or electronic, as long as this
- copyright notice is retained on all copies. Commercial
- redistribution is allowed and encouraged; however, the author
- would like to be notified of any such distributions.
+ copyright notice is retained on all copies.
</para>
<para>
@@ -107,8 +95,6 @@
</sect2>
- <!-- Section2: disclaimer -->
-
<sect2 id="disclaimer">
<title>Disclaimer</title>
@@ -140,8 +126,6 @@
</sect2>
- <!-- Section2: credits -->
-
<sect2 id="credits">
<title>Credits</title>
@@ -149,16 +133,13 @@
This document is based on many files, previously hosted
in the phpdoc module at cvs.php.net, containg information
about several distinct subjects, ranging from generating
- the HTML files from XML sources, to starting a new translation.
+ the HTML files from XML sources to starting a new translation.
This is a central place for all these things. We tried to
- include the original authors in the authors list of
- this file.
+ include the original authors in the authors list of this file.
</para>
</sect2>
- <!-- Section2: feedback -->
-
<sect2 id="feedback">
<title>Feedback</title>
@@ -166,169 +147,234 @@
Feedback is most certainly welcome for this document. Without your
submissions and input, this document wouldn't exist. Please send
your additions, comments and criticisms to the following email
- address : <email>&email.phpdoc;</email>.
+ address: <email>&email.phpdoc;</email>.
</para>
</sect2>
-
</sect1>
- <!-- Section1: about: END -->
+<!-- New Section: Getting Started - - - - - - - - - - - - - - - - - -->
-
- <!-- Section1: getting-started -->
-
<sect1 id="getting-started">
<title>Getting Started</title>
<para>
- The PHP documentation is written in XML using the <ulink
- url="&url.docbookdtd;">DocBook DTD</ulink>. The viewable manual,
- and other formats such as PDF and RTF, are created using <ulink
- url="&url.jade;">Jade</ulink> and <ulink url="&url.nwalsh;">Norman
- Walsh's Modular DocBook Stylesheets</ulink>. There are other
- tools used to produce some other formats and files. You
- can find information about them in the appropriate places
- in this documentation.
+ The PHP documentation is written in XML using the <link
+ linkend="docbook">DocBook DTD</link>. If you would like
+ to contribute to the PHP documentation work, you need
+ to at least now the very basics of XML and DocBook.
</para>
<para>
- In addition to the above tools, you will need your favorite text
- editor and a working <ulink url="&url.cvs;">CVS</ulink>
- installation. Although it is possible to use a simple text editor
- such as vi or notepad to write the XML files, it is recommended
- to use an XML/SGML editor that helps you along and makes sure
- your document is proper XML conforming to the used document
- type definition (DTD). A very good (and free) XML/SGML editor
- is Emacs+PSGML. Both Emacs and CVS are already part of just
- about every Linux distribution available, and they are also
- ported to Windows 95/NT.
+ The XML files are stored on a central server, and
+ can be reached with a <link linkend="cvs">CVS</link>
+ client. There are many CVS clients out there, although
+ we recommend one command line tool.
</para>
<para>
- You will also need <ulink url="&url.autoconf;">autoconf</ulink> to
- build the <emphasis>phpdoc</emphasis> GNU configure script. Many
- distributions come with autoconf already installed. The latest
- copy can be found at:
- <itemizedlist>
- <listitem>
- <simpara><ulink url="&url.autoconf.ftp;">&url.autoconf.ftp;</ulink></simpara>
- </listitem>
- </itemizedlist>
+ You will need more programs and tools to manipulate the
+ XML files and test their content for errors. What tools
+ you need depends on the operating system you use. Linux
+ or some sort of Unix is recommended, although many things
+ in phpdoc works on Windows. You will find more information
+ about the tools you need in the
+ <link linkend="tools-setup">tools</link> section.
</para>
<para>
- <emphasis>
- If you have information about other good XML editors and/or tools
- not mentioned here, please send it to the maintainer,
- <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>.
- </emphasis>
+ If you have problems not covered in this document,
+ write in to <email>&email.phpdoc;</email> and ask.
</para>
- <sect2 id="obtaining-tools">
- <title>Obtaining the Tools</title>
+ </sect1>
+
+<!-- New Section: Tools Setup - - - - - - - - - - - - - - - - - - - -->
+
+ <sect1 id="tools-setup">
+ <title>PHPdoc tools</title>
+
+ <para>
+ What tools you need depends on the operating system you use.
+ Linux or some sort of Unix is recommended, although many
+ things in phpdoc works on Windows. The very basic things
+ you need to work:
+ <itemizedlist>
+ <listitem><simpara>CVS account</simpara></listitem>
+ <listitem><simpara>CVS client</simpara></listitem>
+ <listitem><simpara>Text editor</simpara></listitem>
+ </itemizedlist>
+ The basic process is to check out (~download) the file
+ using the CVS client, then edit it, and finally commit
+ (~upload) it to the server. Of course you can find better
+ tools to edit XML files than a simple text editor, it
+ is just the absolute minimum. Some more useful tools:
+ <itemizedlist>
+ <listitem><simpara>XML [capable] editor</simpara></listitem>
+ <listitem><simpara>Tools to test the edited file</simpara></listitem>
+ </itemizedlist>
+ In the folowing paragraphs, you can find information about
+ how to obtain these tools and how to make them work for you.
+ </para>
- <para>
- To simplify the installation process of the tools necessary to
- write PHP documentation, we have chosen to detail how to download
- and install the source RPMs from a sourceware mirror. You will
- need a working copy of <ulink url="&url.rpm;">RPM</ulink> installed
- on the machine you wish to install these tools on.
- </para>
+ <para>
+ The last item in the above list (test the edited file) is
+ the hardest to get working, as you need a copy of the
+ <link linkend="docbook">DocBook files</link>, and several
+ other tools. The viewable manual, and other formats such as
+ PDF and RTF, are created using <ulink url="&url.jade;">Jade</ulink>
+ and <ulink url="&url.nwalsh;">Norman Walsh's Modular DocBook
+ Stylesheets</ulink>. There are other tools used to produce some
+ other formats and files. It is recommended to set up the style
+ sheets and Jade to be able to test your contributions. Otherwise
+ you can easily cause headaches to other team members.
+ </para>
+ <sect2 id="tools-on-linux">
+ <title>Tools on Linux</title>
+
<para>
- These tools are all seperate packages and can be downloaded and
- installed directly from the author's websites if you choose to do
- so. You do not have to use these source RPMs, but installing from
- the author's seperate packages is out of the scope of this HOWTO.
+ Although many tools are preinstalled on the majority of
+ the Linux systems, we collected some useful information
+ about how they can be obtained and installed, if your
+ system misses them.
</para>
-
+
<para>
- The RPMs with the necessary software can be downloaded from one of
- the following URLs:
+ You will need your favorite text editor and a working
+ <link linkend="cvs">CVS</link> installation. Although
+ it is possible to use a simple text editor such as vi
+ to write the XML files, it is recommended to use an
+ XML/SGML editor that helps you along and makes sure your
+ document is proper XML conforming to the used document type
+ definition (DTD). A very good (and free) XML/SGML editor
+ is Emacs+PSGML. Both Emacs and CVS are already part of just
+ about every Linux distribution available.
</para>
<para>
+ You will also need <ulink url="&url.autoconf;">autoconf</ulink> to
+ build the <emphasis>phpdoc</emphasis> GNU configure script. Many
+ distributions come with autoconf already installed. The latest
+ copy can be found at:
<itemizedlist>
<listitem>
- <simpara>
- <ulink url="&url.docbookmirror1;">&url.docbookmirror1;</ulink>
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <ulink url="&url.docbookmirror2;">&url.docbookmirror2;</ulink>
- </simpara>
+ <simpara><ulink url="&url.autoconf.ftp;">&url.autoconf.ftp;</ulink></simpara>
</listitem>
</itemizedlist>
</para>
-
+
<para>
- You will need to download the following files:
- <itemizedlist>
- <listitem><simpara>docbook-3.x-5.src.rpm</simpara></listitem>
- <listitem><simpara>jade-1.2.x-4.src.rpm</simpara></listitem>
- <listitem><simpara>jadetex-2.x-0.src.rpm</simpara></listitem>
- <listitem><simpara>psgml-1.2.x-1.src.rpm</simpara></listitem>
- <listitem><simpara>sgml-common-0.1-3.src.rpm</simpara></listitem>
- <listitem><simpara>stylesheets-0.10-2.src.rpm</simpara></listitem>
- </itemizedlist>
+ <emphasis>
+ If you have information about other good XML editors and/or tools
+ not mentioned here, please send it to the maintainer,
+ <ulink url="&email.phpdoc;">&email.phpdoc;</ulink>.
+ </emphasis>
</para>
- <para>
- These packages are updated from time to time. Please make sure
- you download the latest version available from the above sites.
- </para>
+ <sect3 id="obtaining-tools">
+ <title>Obtaining the Tools</title>
- </sect2>
+ <para>
+ To simplify the installation process of the tools necessary to
+ write PHP documentation, we have chosen to detail how to download
+ and install the source RPMs from a sourceware mirror. You will
+ need a working copy of <ulink url="&url.rpm;">RPM</ulink> installed
+ on the machine you wish to install these tools on.
+ </para>
- <sect2 id="installing-tools">
- <title>Installing the Tools</title>
+ <para>
+ These tools are all seperate packages and can be downloaded and
+ installed directly from the author's websites if you choose to do
+ so. You do not have to use these source RPMs, but installing from
+ the author's seperate packages is out of the scope of this HOWTO.
+ </para>
- <para>
- Installing the tools is simple. If you downloaded all of the
- above files into a separate directory by themselves, simply issue
- the folowing command:
- </para>
+ <para>
+ The RPMs with the necessary software can be downloaded from one of
+ the following URLs:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <ulink url="&url.docbookmirror1;">&url.docbookmirror1;</ulink>
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <ulink url="&url.docbookmirror2;">&url.docbookmirror2;</ulink>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ You will need to download the following files:
+ <itemizedlist>
+ <listitem><simpara>docbook-3.x-5.src.rpm</simpara></listitem>
+ <listitem><simpara>jade-1.2.x-4.src.rpm</simpara></listitem>
+ <listitem><simpara>jadetex-2.x-0.src.rpm</simpara></listitem>
+ <listitem><simpara>psgml-1.2.x-1.src.rpm</simpara></listitem>
+ <listitem><simpara>sgml-common-0.1-3.src.rpm</simpara></listitem>
+ <listitem><simpara>stylesheets-0.10-2.src.rpm</simpara></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ These packages are updated from time to time. Please make sure
+ you download the latest version available from the above sites.
+ </para>
+
+ </sect3>
+
+ <sect3 id="installing-tools">
+ <title>Installing the Tools</title>
+
+ <para>
+ Installing the tools is simple. If you downloaded all of the
+ above files into a separate directory by themselves, simply issue
+ the folowing command:
+ </para>
- <para>
- <informalexample>
- <programlisting>
+ <para>
+ <informalexample>
+ <programlisting>
$ rpm -Uvh *.rpm
- </programlisting>
- </informalexample>
- </para>
+ </programlisting>
+ </informalexample>
+ </para>
- <para>
- Or, you can issue them one by one in the following order:
- <informalexample>
- <programlisting>
+ <para>
+ 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
- </programlisting>
- </informalexample>
- </para>
-
- <para>
- That's it. You should now have necessary tools installed to edit
- and verify your PHP documentation contributions.
- </para>
-
- </sect2>
+ </programlisting>
+ </informalexample>
+ </para>
- </sect1>
+ <para>
+ That's it. You should now have necessary tools installed to edit
+ and verify your PHP documentation contributions.
+ </para>
- <!-- Section1: getting-started: END -->
+ </sect3>
+ </sect2>
+ </sect1>
- <!-- Section1: files -->
+<!-- New Section: File Overview - - - - - - - - - - - - - - - - - - -->
<sect1 id="phpdoc-files">
<title>File Overview</title>
+
<para>
There are many files used to produce the several output
formats, and to store the many text and information needed
@@ -367,14 +413,13 @@
</varlistentry>
</variablelist>
</para>
- </sect1>
- <!-- Section1: files: END -->
+ </sect1>
- <!-- Section1: using-cvs -->
+<!-- New Section: CVS - - - - - - - - - - - - - - - - - - - - - - - -->
- <sect1 id="using-cvs">
- <title>Using CVS</title>
+ <sect1 id="cvs">
+ <title>CVS</title>
<para>
The PHP documentation is maintained using <ulink
@@ -853,15 +898,12 @@
</para>
</sect2>
-
</sect1>
- <!-- Section1: generating-docs: END -->
-
- <!-- Section1: writing XML documents -->
+<!-- New Section: Docbook - - - - - - - - - - - - - - - - - - - - - -->
- <sect1 id="writing-xml">
- <title>Writing XML documents</title>
+ <sect1 id="docbook">
+ <title>DocBook XML documents</title>
<sect2>
<title>DocBook for Native Speakers of HTML</title>
@@ -908,11 +950,11 @@
<sect2>
<title>DocBook reference</title>
<para>
- General information and documentation for DocBook can be found at
- <ulink url="&url.docbook-ref;">&url.docbook-ref;</ulink>.
+ For information about the DocBook DTD, look here:
+ <ulink url="&url.docbook-dtd;">&url.docbook-dtd;</ulink>.
</para>
<para>
- Element-by-element DTD reference:
+ There is a DTD reference for DocBook at:
<ulink url="&url.docbook-dtdref;">&url.docbook-dtdref;</ulink>.
</para>
<para>
