Re: [PHP-DOC] writing documentation for php modules From: eschmid+sic <email protected>
Date: 07/13/00

On Thu, Jul 13, 2000 at 02:10:18PM -0700, php user wrote:

> Hi, I am trying to write documentation for a new module.

pspell() funktions I guess?
 
> After a bit of struggling and trying to get some sort of editor to work for
> me and help me write documentation for PHP, I finally gave it up and decided
> to revert to using vi. After all, xml syntax is not all that bad.

IMHO emacs or XEmacs would be the editor of choice for editing XML files.

> Now, here is the question. I do not know how those xml files get converted
> to php files, or to html files that can be viewed on the php site. Also, I
> want to test them and make sure that they are correct before I commit them
> to CVS. Can somebody walk me through the process of getting those .xml files
> and getting them to be viewable in a browser?

The transformation is done with Jade and Norman Walsh's modular
stylesheets. It's the so called DocBook XML DTD which we use for the XML
files.

> In other words, can somebody show me what happens to
> http://cvs.php.net/viewcvs.cgi/phpdoc/en/functions/aspell.xml so that it
> eventually becomes
> http://www.php.net/manual/ref.aspell.php
> ???

This is done by a cron job. You needs only to checkout the CVS repository
with the name "phpdoc" and rename aspeel.xml in en/functions and add this
to the reposiotory.

> How can I make this transformation on my compiter so I can test the .xml
> file before commiting it? Also, when I upload the tested .xml file, do I
> need to do anything special so that it becomes available for viewing from
> php site?

Only to files needs slight changes: manual.xml.in and en/chapters.ent.

Than you can try:

cd phpdoc
autoconf
./configure
make

This works of course only if you have installed Jade correct. With some
GNU/Linux systems a awful task.

> I guess, most of my questions are covered in some nice FAQ or tutorial,
> which I miserably failed to find. If that's the case, please, direct me to
> one.

In the top directory in phpdoc there are some readmes and install files.

-Egon