Kevin van Zonneveld

On Development and Internet System Engineering

7 Steps to better PEAR documentation

| Comments

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. Prerequisites

Install phd

1
2
3
4
5
6
7

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 128M) in /etc/php5/cli/php.ini

Install CVS

In case of Ubuntu:

1

aptitude install cvs

Request access

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

su kevin

cd ~/workspace

cvs -d :pserver:kvz@cvs.php.net:/repository login peardoc

cvs -d :pserver:kvz@cvs.php.net:/repository checkout peardoc

cd peardoc

3. Try building the docs

Let’s just see if everything works:

1
2
3
4
5
6

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:

1

en/package/system/system-daemon/*.xml

Also a ‘homepage’ of your docs can be placed here:

1

en/package/system/system-daemon.xml

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:

1

build/en/html/index.html

You can just point your browser to e.g.: file:///home/kevin/workspace/peardoc/build/ and follow the path to your addition.

Well?

  • Looks good? Goto step 6

  • Looks miserable? Goto step 4

6. Commit your XML

1
2
3
4
5

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

Comments