If you've written a PEAR package, it's probably a good idea to submit some end user documentation. Here's how to do it.
How It Works
- PEAR documentation is stored in XML format in a CVS repository.
- There's a tool called _phd _that can convert this XML documentation to many formats: HTML, PDF, CHM, etc.
- The PEAR website periodically checks out the XMLs and uses phd to build all required documentation.
- The language: 'en' is leading for all other languages. So make your changes there.
So basically you:
- Save the current documentation
- Add your own
- Build & review the documentation locally
- Submit your addition (with CVS)
In This article..
I'm going to use
- System_Daemon as example PEAR package.
kvzas CVS username
kevinas workstation username
~/workspaceas project location
- Ubuntu as Operating system.
So please just substitute these specifics with your own.
$ pear install Console_CommandLine $ pear install Console_Getopt $ pear channel-discover doc.php.net $ pear install doc.php.net/phd-beta
I also needed to up my memory limit (I set it to
In case of Ubuntu:
$ aptitude install cvs
If you're planning on maintaining these docs yourself.. You need write-access to the CVS repository.
- Request CVS karma for peardoc (you'd best ask someone on #PEAR at EFnet IRC)
- Request CVS access
2. Save Current Documentation
Let's checkout the peardoc folder of the CVS repository
At first you should try to get the pear manual compiled
$ su kevin $ cd ~/workspace $ cvs -d :pserver:email@example.com:/repository login peardoc $ cvs -d :pserver:firstname.lastname@example.org:/repository checkout peardoc $ cd peardoc
3. Try Building the Docs
Let's just see if everything works:
$ php configure.php # The command configure.php told you to execute, in my case: $ phd -L en -f xhtml -t pearchunkedhtml -o build/en -d .manual.xml
If this fails, fix it first.
4. Write Your Own XML Docs
And so in this case the path to store my different chapters as XMLs would be:
Also a 'homepage' of your docs can be placed here:
What Should the XML Look Like?
I've just looked at other packages like Console_Table, and used them as example.
5. ReBuild Peardoc
Again, build the docs, and checkout the generated HTML output stored in
You can just point your browser to e.g.: file:///home/kevin/workspace/peardoc/build/ and follow the path to your addition.
- Looks good? Goto step 6
- Looks miserable? Goto step 4
6. Commit Your XML
$ cvs add en/package/system/system-daemon/*.xml $ cvs add en/package/system/system-daemon.xml $ cvs commit
7. There Is No Step 7
Thanks to Christian Weiske for holding my hand while I was taking these first steps ; )