2009Q3 Grant Proposal: wxPerl Documentation


Eric J. Roode, ROODE on CPAN.


[hidden email] or [hidden email]

Amount Requested:

$2500 for Q3 2009.


Write a lot of much-needed documentation for wxPerl.

Benefits to the Perl Community

Perl has a reputation as a language that is not suited for GUI development. This is silly; Perl is as suited for GUI as any other language. But the learning curve for most of Perl's GUI toolkits (with the possible exception of Tk) is steep, and good documentation is sorely needed.

This project will lessen the learning-curve for developing modern GUI applications in Perl, and provide reference materials that even experienced wxPerl programmers can find useful.


A. Overall project deliverables

  1. A guide to interpreting the wxWidgets API guide (which is oriented toward C++ programmers) for Perl programmers.

  2. A document listing which wxWidget classes are part of wxPerl, and which ones aren't.

  3. Create screenshots for all Perl-supported wxWidgets, so users can have more of an idea what each widget is.

  4. Create a step-by-step walkthrough for installing wxWidgets and wxPerl on as many platforms as possible.

  5. Convert all wxWidget API docs (oriented toward C++ programmers) to Perl-oriented documents

  6. Review existing tutorials (listed at http://wxperl.sourceforge.net/documentation.html): Ensure that they work with modern perls and modern wxWidget toolkits; ask authors whether the tutorials could be posted to the wxPerl wiki (with updates as necessary).

B. Phase 1 (2009 Q3) deliverables

  1. 100% of item 1 above.

  2. 100% of item 2 above.

  3. 80 screenshots of various Wx widgets, plus short accompanying demo programs that were used to create each.

  4. 100% of item 4 above.

  5. 50 wxWidget class API documents rewritten to describe wxPerl interface instead of wxWidgets interface.

  6. 0% (yeah, zero) of item 6 above.

  7. A report to the Perl Foundation detailing how much time was spent on this project during the quarter, and how much of each goal was delivered.

Project Details

wxPerl is one of the best GUI toolkits for Perl. However, the state of its documentation is poor. My goal is to help to improve it.

This is a huge undertaking, and I expect it to take much longer than just one quarter. So I will detail all the work that needs to be done, and I will list the amount that I think can be accomplished in one quarter. At the end of the quarter, I will assess how much has been accomplished, and will reassess the overall project plan.

There are approximately 600 classes described at http://docs.wxwidgets.org/2.8.4/wx_contents.html, which is the only class documentation referenced from the project documentation page http://wxperl.sourceforge.net/documentation.html. This documentation is designed for C++ progammers, not Perl programmers. For example, there are frequent references to reference parameters, const arguments, and C++ data types. It is not always clear how these should be used in wxPerl.

Of those 600 classes, it is not clear which ones are part of the wxPerl package. All that are should be rewritten to reflect Perl usage instead of C++ usage. Also, they should all include screenshots, so a user can see what each control looks like in action.

There are five tutorials linked on that same documentation page. One was last updated in 2004; the others were written in 2001. It should be verified that they all work with recent perl and wxWidget releases. Probably they should all be reposted to the wxPerl wiki.

I am honestly not sure whether the Phase 1 deliverables that I describe above can all be delivered in 2009 Q3. But that is my best initial estimate, given my time commitment (I pledge to commit 5-10 hours per week to this project for the duration). At the end of the quarter, I will reassess progress and goals, and plan the next phase.

I have been in communication with the wxPerl-users mailing list, asking for ideas and support about this project, and have received encouragement and ideas from notable people on that list. You can review the thread here: http://www.nntp.perl.org/group/perl.wxperl.users/2009/07/msg6524.html


  1. Reinstall wxPerl on at least two of my systems, documenting each step as I go.

  2. Write up the installation process as a step-by-step walkthrough for others to follow in my footsteps. Post these guides to the wxPerl wiki.

  3. Sketch out which wxWidget classes are part of wxPerl, and report my findings to the wxPerl-users mailing list for feedback. Try to get a feel for which are the most "important" classes -- that is, which should be documented first.

  4. Write a nice document about which classes are/aren't included; post this to the wxPerl wiki.

  5. Review the wxDemo program that comes with wxPerl. Compare actual usage of classes to the (C++-oriented) wxWidget documentation. Sketch out a "translation guide". Look for exceptions -- things that the C++ documentation would make you think are done one way, but are done differently in wxPerl.

  6. Write up the results of item 5 as a guide for users.

  7. Begin writing short programs that each demonstrate one widget (probably borrowing from wxDemo). Take a screenshot of each. Post screenshots, and the demo program that generated each, to the wxPerl wiki.

  8. Do lots and lots and lots more of item 7, probably in small batches of 5 or 10. As each batch is completed, send them to the wxPerl project and to the wxPerl wiki.

  9. For a break now and then, review the existing tutorials described above. Duplicate them on my systems. Run them -- do they work? Critique them for style -- do they work under 'use strict'? Other "modern perl"-isms?

  10. Begin rewriting the wxWidget (C++-oriented) class documentation to be wxPerl-oriented.

  11. Do lots and lots and lots more of item 10. Some of this can probably be at least partially automated, but I'll still need to check over each one by hand. It probably makes sense to do this in small batches of 5 or 10 at a time. As each batch is completed, send them to the wxPerl project and to the wxPerl wiki.

Project Schedule

The project as a whole will take much longer than a quarter; it may go a year or longer. I think that breaking it up into quarter-sized chunks makes sense. It gives some concrete, short-term benefit to the Perl GUI community, and also gives the opportunity to reassess and re-plan in a few months.


My name is Eric J. Roode. I have been a Perl programmer since about 1995, on a variety of platforms (unix, linux, solaris, windows). I am the author of the Readonly, Time::Format, Time::Normalize, Text::Printf, Regexp::Common::time, and other modules. Not all of those are particularly monumentous contributions to the Perl community, but you can look at the documentation I distributed with each of them to get an idea of the quality of my work as a documentor.


I will admit that this would be quite useful. I've looked at the (lack of) wxPerl documentation and gotten scared at attempting to learn it.

I don't have anything add beyond Curtis's comments. I have had the same experience.

I think the learning curve of wxPerl is way too steep that made it very difficult to write a large application in it. We still struggle in the Padre project because of our lack of understanding. I think having a good documentations and a good set of stand alone examples of wxPerl would help a lot our project as well.

As total newbie that attempt to learn Perl using wxPerl/GUI, lack of documentation is a big hurdle, I vote for this proposal.

I picked up Perl because it claimed to be a general purpose programming language. I work as a web-developer since 2003. I made some really serious WEB-based projects. From time to time it happens to write some small GUI apps. I use the Mozilla platform (XUL/JavaScript) for that.

I hope the "wxPerl Documentation" will make me turn back to Perl.

++ for attempting to do something about Perl's poor GUI support.

I agree. This is a good idea and could help accelerate the use of Perl as a GUI application framework.

About TPF

The Perl Foundation - supporting the Perl community since 2000. Find out more at www.perlfoundation.org.

About this Entry

This page contains a single entry by Alberto Simões published on August 10, 2009 12:28 PM.

2009Q3 Grant Proposal: Improve the visual design of Perl websites was the previous entry in this blog.

2009Q3 Grant Proposal: perl core memory improvements is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.


OpenID accepted here Learn more about OpenID
Powered by Movable Type 6.2.2