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
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 ; )