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.
kvz as CVS username
kevin as workstation username
~/workspace as project location
Ubuntu as Operating system.
So please just substitute these specifics with your own.
1 2 3 4 5 6 7
I also needed to up my memory limit (I set it to 128M) in /etc/php5/cli/php.ini
In case of Ubuntu:
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
1 2 3 4 5 6 7 8 9
3. Try building the docs
Let’s just see if everything works:
1 2 3 4 5 6
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
1 2 3 4 5
7. There is no step 7
Thanks to Christian Weiske for holding my hand while I was taking these first steps ; )