Lot 49: Greg Beaver's blog

As Allan Kozinn of the New York Times reports, the classical music industry is doing just fine.  In fact, it is a growth industry, and the numbers support this assertion, contrary to all the doomsday hemming and hawing.  What is happening is what has always happened: a shift in what classical music means.  Change is an essential part of vibrancy in culture, as the world refuses to stand still.

Go figure .

My favorite part of the article is where he quotes a 1967 NYTimes article claiming that classical music is dying with nice figures like "audiences are down 40%" and complaining about high ticket prices.  Since then, the number of halls actively presenting classical music year-round in New York has doubled, and the same is true around the nation.

The full article is at: http://www.nytimes.com/2006/05/28/arts/music/28kozi.html

For every complex problem there is an answer that is clear, simple and wrong

--H.L. Mencken

Put bluntly, I think lumping XmlHttpRequest, DOM, Flash MX and any other dynamic browser-based solution into a single name is misleading. I've always hated crap like "LAMP" and other cutesy names. They only serve to obfuscate the meaning of the technologies and to create a hype-of-personality surrounding BS terms that never meant anything in the first place, even alienating people who are not "in the know."

We don't need a "Web 2.0" and the name itself is misleading - all supposed Web 2.0 stuff is still TCP/IP-based. To me Web 2.0 would imply some different kind of transmission protocol like mind-reading. Ooh, I have a catchy name to define this exciting new protocol that's better than "Web 2.0": "Synapse Telepathy-based Universal Protocol/Interpersonal Dynamics."

We have had many inquiries from people who wish to assist with developing phpDocumentor or with PEAR.  For those of you have written, thank you.  However, most requests are along the lines of "how can I help?" and typically do not continue when we answer. Unfortunately, I've taken to a rather nihilistic view of these inquiries. Interestingly enough, most people who do end up helping out skip the question "how can I help?" altogether!

The question itself is not useful because there is plenty of evidence out there suggesting how to help out. Both PEAR and phpDocumentor have bug trackers [1]. These trackers list issues that have not been solved, and features that have not been implemented. If you want to help out a project, take a look at the bugs, choose one, and write a message along the lines of this (feel free to cut and paste):

"Hi,

my name is XXXX and I would like to fix Bug #1234 for the [fill in project name like PEAR or PhpDocumentor] project. If this issue has already been handled, I would instead like to take on Bug #1235. Do you have any objection?

Thanks,
Joe Shmoe"

Don't even wait to hear back from us, the next step is to fix the bug. Become good friends with the "cvs diff -u" command, and use that to email a patch back. The email should look something like:

"Hi,

I have a fix for Bug #1234, attached to this email as a unified diff against current CVS for [fill in project name like PEAR or PhpDocumentor]. If it looks good, could you commit the patch and close the bug?

Thanks,
Joe Shmoe"

If, in the course of attempting to fix the bug, you encounter a problem (such as not being able to access CVS), or don't understand something about the code, do not give up! Instead, send an email along these lines:

"Hi,

While attempting to fix Bug #1234, I have run up against some confusion. [...Describe what you don't understand, or what is not working the way you expect]. Can you help me figure this out?

Thanks,
Joe Shmoe"

Where, you might ask, should I send these emails? For both projects, there are public mailing lists devoted to the development of the projects. The best thing you can do is to send a message to these lists, and copy the lead developer (for PEAR/phpDocumentor, me) of the project in question. PEAR's list is pear-core@lists.php.net, and phpDocumentor's list is phpdoc-devel@lists.bluga.net. These are standard mailing lists, so the usual drill of sending a message to "phpdoc-devel-subscribe@lists.bluga.net" or "pear-core-subscribe@lists.php.net" will suffice to get you started. You can email me directly by taking the domain name of this blog and substituting an "at" symbol for the first period before the quartet part of the domain.

Until we have a history of working together, always assume that your code needs work, and set aside concerns of ego.  It doesn't matter how much coding experience you have, what matters is diligence, humility and the ability to respond productively to criticism of the code itself (i.e. try to fix problems and then re-send the patch).  In most cases, if a patch fixes a bug but is slightly flawed, I will simply commit it with modification to fix the slight flaw.  If you're following the pear-cvs@lists.php.net list (or php.pear.cvs through news.php.net), you can see the way I have modified your patch, and learn for the next bug you fix or feature you implement.  Above all, don't be intimidated, it's just PHP, and even if you do submit total crap code, it will be caught by either the developers or the unit tests (at least for PEAR).

As for helping out with phpDocumentor, it may be overwhelming to see the number of bugs in the list. What we really need from a developer is to develop a set of regression tests, so that as we clean the source code, we don't break anything. For instance, I plan to streamline all of the parsers, and to remove or revamp the internal caching mechanism inside conversion. This will be a huge project, even though the change is incremental, and will be the first step towards implementing the memory hogging.

PEAR 1.4.x is in a bugfix mode, but we are working on version 1.5.0. There are already tons of regression tests in place, so this is more a question of helping out with design and development of new features. Currently, there is one open bug report about a fatal error when installing through a third-party system (gentoo ebuild) that needs looking at and could be an easy first project for a new developer.

Frankly, if you wish to help out, you almost don't need to ask permission!  Just email with a patch solving a bug or implementing a feature. What's the worst thing that could happen? You'd spend some time learning how these vastly important projects actually work, and maybe even improve your own PHP expertise in the process. Even if your code is not accepted (bug fixes are almost always accepted as submitted, feature requests may not be), you come out ahead, and in the best case, you can get credit for fixing an issue that affects thousands and thousands of users. Not too bad, eh?

[1]

PEAR bug tracker

phpDocumentor bug tracker at PEAR

phpDocumentor bug tracker at sourceforge.net

Recently, phpDocumentor 1.3.0RC6 was released (1.3.0 stable is coming soon, stay tuned).  In this release, I finally got around to fixing the problem with source highlighting and CSS in the HTML templates.  If you have been using your own custom template based on the standard distributed templates, you will need to make a few changes.  Most importantly, you'll need to go into your options.ini and make changes similar to this:

http://cvs.php.net/viewcvs.cgi/pear/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/options.ini?r1=1.2&r2=1.3

In addition, you'll want to make sure your style sheet has an entry similar to this:

http://cvs.php.net/viewcvs.cgi/pear/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/templates/media/stylesheet.css?r1=1.1&r2=1.2

If you based your template off of another of the templates, you can see the exact choices you need by examining CVS of phpDocumentor (the above links can be used to navigate to the template you need)

Happy documenting!

If you are a U.S. Citizen, it is time to call your Representatives and Senators. They're trying to gut Net Neutrality, a crucial component of the internet's success and its freedom. Net Neutrality guarantees that all online speech is treated equally and prevents Internet providers like AT&T from deciding which websites work best on your computer. Without it, these companies can decide what you see and do online. In other words, without Net Neutrality AT&T could conceivably decide to limit the bandwidth for iTunes because Microsoft pays them to increase the bandwidth for MSN Music.

You can read more about the effort to fight this terrifying idea at http://www.savetheinternet.com/.

Yesterday and today I released phpDocumentor 1.3.0RC6. Aside from a number of exciting features and many important bug fixes, including some bugs opened over 2 years ago (!) this release is unique in another way: in addition to working as a PEAR-installable package, it also works as an extracted file.

This is a subtle but revolutionary change. In order to do this, we have to take advantage of some interesting possibilities that package.xml 2.0 provides. In fact, I designed several of the features of package.xml 2.0 to support this duality. In particular, it is possible to bundle a file and completely ignore it. We use this feature to handle the duality of the "phpdoc" command itself.

When installed through PEAR, a file named "pear-phpdoc" is installed as "phpdoc", and if installed on windows, "pear-phpdoc.bat" is installed as "phpdoc.bat." Also bundled in the archive are the original "phpdoc" and "phpdoc.bat" commands needed to run phpDocumentor out of the box just by extracting the archive. These files are simply ignored by the PEAR installer.

Another feature unique to package.xml 2.0 that makes this possible is the usage of package-time file tasks. In particular, the replace task, which is used to set the version of phpDocumentor as displayed by the actual generation and the docbuilder web interface.

In addition, I finally updated the manual at http://www.phpdoc.org/manual to the current version.

So in short, things are coming together finally.