Kristina Chodorow's Blog
Uncategorized
phpdoc hell
Feb 23rd
I’ve been fighting with phpdoc for about a week now, trying to figure out how to document my extension, which is a combination of PHP and C code. I finally figured it out, and since I haven’t seen this documented anywhere, I figured I’d reproduce the steps here:
Download phpdoc from CVS. No! Not PEAR, you fool! CVS! For some reason, the package you download with PEAR and the package you get from CVS are completely different. Luckily, PHP has some instructions on how to download the package with CVS.
For my lovely Javadoc-style PHP-code comments, phpdoc can be used to convert them to XML:
$ phpdoc -d path/to/php/srcs -t output -o XML:DocBook/peardoc2:default
Cool! Now you have your PHP documentation converted. Now for the C code. CVS phpdoc (and only this phpdoc, not PEAR phpdoc) has a script in scripts/docgen called docgen.php. You use this as follows:
$ php docgen.php --output tmp --extension extname
That gives you an outline to fill in for you C documentation. Now you just need to mush them together and generate the manual, to see what it looks like. This is where I got stuck. Here’s what I figured out: in phpdoc/manual.xml.in, add 1 line:
&reference.mongo.book;
…except replace “mongo” with whatever your extension’s name is.
Put your xml documentation in the directory phpdoc/en/reference/mongo. In phpdoc/en/reference/ add a file called entities.mongo.xml, and use the other entities files as your guide for its contents.
To actually generate the documentation, go to phpdoc/ and run:
$ php configure.php --with-partial=book.mongo
$ phd -d /path/to/phpdoc/.manual.book.mongo.xml
Et voila. Point your browser to file:///path/to/phpdoc/html/ref.mongo.html and you can see your documentation.
Pain in my CVS
Feb 21st
This is pretty geeky, so sorry non-technical reader. There’s a glossary at the bottom if you’d like to follow along.
I’ve been developing a PHP database driver for work, and this week I proposed it as a new PECL (pronounced “pickle”) package. Unfortunately, they use CVS for their packages. I’m used to Git.
So, I created a cvsroot/ directory and imported my driver to it. After a couple tries, I figured that out. Then I was confused, all my files were suddenly named file,txt instead of file.txt. Then I realized that this was my master repository, and I had to check out code from there. So, I made a cvsstuff/ directory and did
$ cd cvsstuff $ cvs co mongo
And it did the right thing! Cool.
So now I had to do it with php.net’s remote repository. I tried checking out a couple packages to get a feel for the syntax. Then I figured out my import command, triple checked it, and was about to press enter when… hmm, where was it getting the path to the directory I was importing? I was in my home directory, so… oh, crap. So, I almost uploaded my home directory to a public repository on php.net (for Windows users, this is roughly equivalent to uploading My Documents). My hand was hovering over the enter key, but I didn’t!
I successfully uploaded my driver, and all was well.
Non-technical person explanation:
- PHP
- you’ve heard of it, maybe? It’s a programming language, like C++ or Java, except it’s usually used for making webpages.
- Database
- information storage, usually can be pictured as a bunch of tables. MySQL is the most famous, my company’s is called Mongo (www.mongodb.org).
- Database driver
- when you create a database, like our company did, you want everyone, regardless of what language they program in, to be able to use it. So you write drivers, which translate a programming language to database-speak.
- PECL package
- PHP has a system set up so, if someone write a useful program in PHP, it’s easy for you, halfway around the world, to download it and use it. It’s called PEAR, and it lets you type:
$ pear install cool-package
And then you have cool-package installed on your system, too. All the packages are open source.
- CVS/Git
- When you’re working on a programming project, often you’re like, “I’ll just fix this little thing here.” And then when it’s fixed, suddenly no one can log in and you can’t remember exactly what you changed and the your company crashes and burns. And that is where version control software comes in. Whenever someone makes a change, they use a program like CVS to say “I’ve changed lines 4, 6, and 23 of MyProg.java.” Then they send this change to the central computer, who has the master code and updates it with the person’s change. If the change turns out to break stuff, there’s a record of exactly what changed and you can revert the code back to its original state. CVS is the grand-daddy of all version control, Git is another, more recent version control system.
Nifty Flash Thing
Feb 19th
Someone at work showed me http://www.wordle.net/create, which is cool.
Using this blog’s URL (one whole post!) gives:
which I suppose it mostly accurate. I think this blog will be less about CURRENT in the future (even though that sounds… strange), and more about cartooning, Linux, reading, and stuff like that. If I remember, I’m going to repeat the experiment in a few months, see how things have changed.
Downloading the Archives
Feb 18th
Usually I discover new comics by reading a recent one I like, then starting from the beginning and reading the whole oeuvre. Unfortunately, I’m often not connected to the internet. So, if you like my comics:
- Email me and let me know. Artistic insecurity knows no bounds.
- Use this handy-dandy shell script to download them to your Linux box (you are running Linux, aren’t you?):
#!/bin/bash
i=1
max=$CURRENT_NUM
while [[ $i -le $max ]]; do
wget "http://www.snailinaturtleneck.com/comics/images/siat$(printf "%04d" $i).jpg" -O siat$(printf "%04d" $\
i).jpg
let "i=$i+1"
done
This will only hold you until I’ve done 10,000 cartoons, but that should be a few weeks, at least. You’ll have to replace $CURRENT_NUM with the number of the current comic. To figure out what this is, go to www.snailinaturtleneck.com and the title of the comic will start with the current number.
Anyway, I hope you enjoy these cartoons. Questions, comments, and suggestions are always welcome. Also, criticism, hate mail, death threats, whatever. Send it all to kristina@snailinaturtleneck.com.
* Not worth reading anymore, now every blog post is him promoting himself. I do recommend the archives, which have some really interesting information about investing, finances, that sort of thing.
Subscribe to all posts
