goba Sat Sep 8 14:40:10 2001 EDT
Added files:
/phpdoc/howto howto.xml howto.ent
Log:
Adding howto.xml and howto.ent (previously phpdoc-howto.xml and phpdoc-howto.ent)
Index: phpdoc/howto/howto.xml
+++ phpdoc/howto/howto.xml
<?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;
<!ENTITY % phpdoc-howto.entities SYSTEM "./phpdoc-howto.ent">
%phpdoc-howto.entities;
]>
<article id="index">
<!--
MISC NOTES:
ADD:
Meta-q information
Meta-Shift-^ information
How to add a new section to the manual itself.
-->
<artheader>
<author>
<firstname>Daniel</firstname>
<surname>Beckham</surname>
<authorblurb>
<simpara>
(<ulink url="mailto:&email.danbeck;";>&email.danbeck;</ulink>)
</simpara>
</authorblurb>
</author>
<title>The PHP Documentation Contribution HOWTO</title>
</artheader>
<!-- Section1: intro -->
<sect1 id="about">
<title>About This Document</title>
<para>
phpdoc HOWTO full introduction
</para>
<!-- Section2: copyright -->
<sect2 id="copyright">
<title>Copyright Information</title>
<para>
This document is copyrighted (c) 2000 Daniel Beckham and is
distributed under terms stated below.
</para>
<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.
</para>
<para>
All translations, derivative works, or aggregate works
incorporating this document must be covered under this copyright
notice. That is, you may not produce a derivative work from this
document and impose additional restrictions on its
distribution. Exceptions to these rules may be granted under
certain conditions; please contact the HOWTO coordinator at the
address given below.
</para>
<para>
In short, we wish to promote dissemination of this information
through as many channels as possible. However, we do wish to
retain copyright on the HOWTO documents, and would like to be
notified of any plans to redistribute the HOWTOs.
</para>
<para>
If you have any questions, please contact Daniel Beckham,
<email>&email.danbeck;</email>
</para>
</sect2>
<!-- Section2: disclaimer -->
<sect2 id="disclaimer">
<title>Disclaimer</title>
<para>
No liability for the contents of this documents can be
accepted. Use the concepts, examples and other content at your own
risk. As this is a new edition of this document, there may be
errors and inaccuracies, that may of course be damaging to your
system. Proceed with caution, and although this is highly
unlikely, the author(s) do not take any responsibility for that.
</para>
<para>
All copyrights are held by their by their respective owners,
unless specifically noted otherwise. Use of a term in this
document should not be regarded as affecting the validity of any
trademark or service mark.
</para>
<para>
Naming of particular products or brands should not be seen as
endorsements.
</para>
<para>
You are strongly recommended to take a backup of your system
before major installation and backups at regular intervals.
</para>
</sect2>
<!-- Section2: credits -->
<sect2 id="credits">
<title>Credits</title>
<para>
Thanks to the following people for contributions and critisism:
</para>
</sect2>
<!-- Section2: feedback -->
<sect2 id="feedback">
<title>Feedback</title>
<para>
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.danbeck;</email>.
</para>
</sect2>
</sect1>
<!-- Section1: about: END -->
<!-- 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 3.0 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>.
</para>
<para>
A DTD reference for DocBook can be found <ulink
url="&url.dtdref;">here</ulink>.
</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. If you don't already have a favorite text editor, I
recommend Emacs, one of the best XML/SGML editors around. 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.autoconf.ftp;">&url.autoconf.ftp;</ulink></simpara>
</listitem>
</itemizedlist>
</para>
<sect2 id="obtaining-tools">
<title>Obtaining the Tools</title>
<para>
To simplify the installation process of the tools necessary to
write PHP documentation, I 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>
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>
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>
</sect2>
<sect2 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>
$ rpm -Uvh *.rpm
</programlisting>
</informalexample>
</para>
<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>
</sect1>
<!-- Section1: getting-started: END -->
<!-- Section1: cvs -->
<sect1 id="using-cvs">
<title>Using CVS</title>
<para>
The PHP documentation is maintained using <ulink
url="&url.cvs;">CVS</ulink> (<emphasis>Concurrent
Versions System</emphasis>). CVS allows the documentation
contributors to make changes to the different files that make up
the PHP documentation without stepping on each other's toes.
</para>
<para>
This section is not intended to be a CVS tutorial, only a quick
walkthough to help you get started checking out out the
<parameter>phpdoc</parameter> tree and commiting your changes. The
complete CVS documentation and can be found at <ulink
url="&url.cvs;">&url.cvs;</ulink>.
</para>
<para>CVS tutorials can be found at:
<itemizedlist>
<listitem>
<simpara><ulink url="&url.cvstut1;">&url.cvstut1;</ulink></simpara>
</listitem>
<listitem>
<simpara><ulink url="&url.cvstut2;">&url.cvstut2;</ulink></simpara>
</listitem>
</itemizedlist>
</para>
<sect2 id="cvs-account">
<title>Obtaining a CVS Account</title>
<para>
First, before you can actually make documentation changes, you
need write access to the <ulink
url="&url.cvs.php;">cvs.php.net</ulink> CVS repository. You can
always checkout a module anonymously, but you can not commit
changes unless you have an account.
</para>
<para>
Obtaining a CVS account at php.net isn't difficult, but you need
to do two things:
<itemizedlist>
<listitem>
<simpara>
Send mail to <ulink
url="mailto:&email.group.php;";>&email.group.php;</ulink>.
Explain what you would like to do with the CVS account
(contribute to the PHP documentation). Also give a little
information and background about yourself so the developers
understand where you are coming from.
</simpara>
</listitem>
<listitem>
<simpara>
Once someone from the development team responds to your e-mail,
you will need to go to <ulink
url="&url.cvsaccount.php;">&url.cvsaccount.php;</ulink> and fill
out the formal request form.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Both of the above steps and other information about CVS accounts
at cvs.php.net can be found on the same page as the request form,
<ulink url="&url.cvsaccount.php;">&url.cvsaccount.php;</ulink>.
</para>
</sect2>
<sect2 id="login">
<title>CVS Login</title>
<para>
Now that you have write access to the CVS repository, let's setup
a few variables in your <filename>.cvsrc</filename> file, add a
<literal remap="tt">CVSROOT</literal> environment variable and
login to the CVS repository.
</para>
<para>
If you don't already have a <filename>.cvsrc</filename> file in
your home directory, create one now and add the following lines to
it:
<informalexample>
<programlisting>
cvs -z3
update -d -P
checkout -P
diff -u
</programlisting>
</informalexample>
</para>
<para>
Each time you issue commands to the CVS repository, you have to
specify the repository's cvsroot directory like this:
<informalexample>
<programlisting>
$ cvs -d :pserver:<parameter>username</parameter>@cvs.php.net:/repository checkout
<parameter>phpdoc</parameter>
</programlisting>
</informalexample>
</para>
<para>
Instead of telling <command>cvs</command> where the repository is
each time, you can set a default CVS repository in your <literal
remap="tt">CVSROOT</literal> environment variable.
</para>
<para>
For <literal remap="tt">sh</literal> and <literal
remap="tt">bash</literal> users add the following to your
<filename>.bashrc</filename> or <filename>.profile</filename>
file.
<informalexample>
<programlisting>
CVSROOT=:pserver:<parameter>username</parameter>@cvs.php.net:/repository
export CVSROOT
</programlisting>
</informalexample>
</para>
<para>
For <literal remap="tt">csh</literal> and <literal
remap="tt">tcsh</literal> users add the following to your
<filename>.cshrc</filename> or <filename>.tcshrc</filename> file.
<informalexample>
<programlisting>
setenv CVSROOT :pserver:<parameter>username</parameter>@cvs.php.net:/repository
</programlisting>
</informalexample>
</para>
<note>
<para>
The <literal remap="tt">CVSROOT</literal> environment variable
won't be set until the next time you log in.
</para>
</note>
<para>
Now that you have the prep work out of they way, you will need to
login to the CVS repository. Issue the following command:
<informalexample>
<programlisting>
$ cvs login
</programlisting>
</informalexample>
</para>
<para>
Or, if you don't have your <literal remap="tt">CVSROOT</literal>
set, make sure you supply the correct <literal
remap="tt">cvsroot</literal>:
<informalexample>
<programlisting>
$ cvs -d :pserver:<parameter>username</parameter>@cvs.php.net:/repository login
</programlisting>
</informalexample>
</para>
<para>
You will be asked to supply your password. Once you successfully
login to the CVS respository, your encrypted password is stored in
the <filename>.cvspass</filename> file in your home directory.
You won't need to log back into the same repository again unless
you delete that file.
</para>
</sect2>
<sect2 id="checkout">
<title>Checking Out a Module</title>
<para>
Now it's time to checkout the <parameter>phpdoc</parameter>
module. Incidently, a module is a collection of source
directories and files. Usually it's simply a directory tree in
the CVS repository.
</para>
<para>
<command>cd</command> to a directory you wish to store the
<parameter>phpdoc</parameter> tree under. Wherever you decide to
put it, a <filename>phpdoc</filename> directory will be created
there. Issue the following command:
<informalexample>
<programlisting>
$ cvs checkout <parameter>phpdoc</parameter>
</programlisting>
</informalexample>
</para>
<para>
After some status information about the checkout scrolls by, you
should have a full working copy of the phpdoc module.
</para>
</sect2>
<sect2 id="update">
<title>Updating the Tree</title>
<para>
It's a good idea from time to time to update your copy of the
<parameter>phpdoc</parameter> tree so that you always have the
latest copy. Currently, changes to the tree are made daily so you
should always update your copy before making changes yourself.
</para>
<para>
To update your copy, <command>cd</command> to the
<filename>phpdoc</filename> directory and issue the following
command:
<informalexample>
<programlisting>
$ cvs update
</programlisting>
</informalexample>
</para>
<para>
If you only wish to update a particular file or set of files you
would like to modify, you can pass their filenames along with the
update command:
<informalexample>
<programlisting>
$ cvs update <parameter>file1</parameter>
<optional><parameter>file2</parameter></optional>
</programlisting>
</informalexample>
</para>
<para>
If the files are located beneath the top level
<filename>phpdoc</filename> directory, use the relative paths of
the filenames:
<informalexample>
<programlisting>
$ cvs update <parameter>en/functions/file1</parameter>
<optional><parameter>en/chapters/file2</parameter></optional>
</programlisting>
</informalexample>
</para>
</sect2>
<sect2 id="status">
<title>Checking the Status of Files</title>
<para>
If you've made several changes to your local copy of
<parameter>phpdoc</parameter> and would like to see what files
have been modified, you can ask <command>cvs</command> what the
current status of the file or files is.
</para>
<para>
To see the status of all files in the current directory, issue the
following command:
<informalexample>
<programlisting>
$ cvs status -l
</programlisting>
</informalexample>
</para>
<para>
This will usually generate a huge list, but you can narrow down
the status information by supplying <command>cvs</command>
specific filenames to check the status of:
<informalexample>
<programlisting>
$ cvs status <parameter>file1</parameter>
<optional><parameter>file2</parameter></optional>
</programlisting>
</informalexample>
</para>
<para>
<example>
<title><command>cvs status</command> example</title>
<screen>
===================================================================
File: phpdoc.sgml Status: Locally Modified
Working revision: 1.3 Fri Aug 25 19:14:08 2000
Repository revision: 1.3 /cvsroot/howto/phpdoc/phpdoc.sgml,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
</screen>
</example>
</para>
</sect2>
<sect2 id="commit">
<title>Commiting Changes</title>
<para>
Once you have made changes to a file and validated your XML, you
are ready to commit the change to the CVS repository.
</para>
<para>
When commiting a file or files to the repository, it is polite to
supply an brief message of what you have changed. You do not need
to document every single line you changed, that is part of CVS'
job. However, it is helpful to see a brief summary of what has
changed from version to version without having to study the file
itself.
</para>
<para>
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>
</programlisting>
</informalexample>
</para>
</sect2>
</sect1>
<!-- Section1: using-cvs: END -->
<!-- Section1: generating-docs -->
<sect1 id="generating-docs">
<title>Validating Your Changes and Generating Documentation</title>
<para>
An important part of making contributions to the PHP documentation
is being able to validate your changes and to be able to see what
they will look like in their various forms, whether that is in
HTML, Adobe PDF or RTF format.
</para>
<sect2 id="the-makefile">
<title>The Makefile</title>
<para>
The <filename>Makefile</filename> controls serveral aspects of how
documenation is validated and created. To generate a
<filename>Makefile</filename> from a fresh checkout,
<command>cd</command> to the <filename>phpdoc</filename> directory
and issue the following commands:
<informalexample>
<programlisting>
$ autoconf
$ ./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 validate the documenation
changes you have previously made:
<informalexample>
<programlisting>
$ cd phpdoc
$ make test
</programlisting>
</informalexample>
</para>
<para>
Which will generate output similar to this:
</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
</screen>
</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 <para> 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>
<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>
</sect1>
<!-- Section1: generating-docs: END -->
<!-- Section1: working-with-emacs -->
<sect1 id="working-with-emacs">
<title>Working With Emacs</title>
<para>
How to work with emacs, manual.ced, commands, etc.
</para>
<sect2 id="emacs-configuration">
<title>Configuration</title>
<para>
</para>
</sect2>
<sect2 id="emacs-basic-commands">
<title>Basic Commands</title>
<para>
</para>
</sect2>
<sect2 id="emacs-working-with-sgml">
<title>Working With SGML</title>
<para>
</para>
</sect2>
</sect1>
<!-- Section1: working-with-emacs: END -->
<!-- Section1: working-with-vi -->
<sect1 id="working-with-vi">
<title>Working With vi</title>
<para>
How to work with vi, manual.ced, commands, etc.
</para>
<sect2 id="vi-configuration">
<title>Configuration</title>
<para>
</para>
</sect2>
<sect2 id="vi-basic-commands">
<title>Basic Commands</title>
<para>
</para>
</sect2>
<sect2 id="vi-working-with-sgml">
<title>Working With SGML</title>
<para>
</para>
</sect2>
</sect1>
<!-- Section1: working-with-vi: END -->
<!-- Section1: doc-examples -->
<sect1 id="doc-examples">
<title>Documentation Examples</title>
<para>
Documentation formatting and other examples.
</para>
</sect1>
<!-- Section1: doc-examples: END -->
<!-- Section1: misc-notes -->
<sect1 id="misc-notes">
<title>Miscellaneous Notes</title>
<para>
Misc. notes that don't need a full section. (stuff like
http://www.zend.com/phpfunc/, etc.
</para>
</sect1>
<!-- Section1: misc-notes: END -->
</article>
<!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"phpdoc-howto.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/howto/howto.ent
+++ phpdoc/howto/howto.ent
<!--
phpdoc-howto.ent: global entities for the phpdoc HOWTO
-->
<!ENTITY email.danbeck "[EMAIL PROTECTED]">
<!ENTITY email.group.php "[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/";>
<!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/";>
<!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";>
<!ENTITY url.cvsaccount.php "http://www.php.net/cvs-php3.php";>
<!ENTITY url.zend.phpfunc "http://www.zend.com/phpfunc/";>
