2009Q3 Grant Proposal: wxPerl Documentation
Mon, 10-Aug-2009 by
Alberto Simões
edit post
<![CDATA[
<dl>
<dt><strong>Name:</strong>
<dd>
<p>Eric J. Roode, ROODE on CPAN.</p>
</dd>
</li>
<dt><strong>Email:</strong>
<dd>
<p>[hidden email] or [hidden email]</p>
</dd>
</li>
<dt><strong>Amount Requested:</strong>
<dd>
<p>$2500 for Q3 2009.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2>Synopsis</h2>
<p>Write a lot of much-needed documentation for wxPerl.</p>
<h2>Benefits to the Perl Community</h2>
<p>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.</p>
<p>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.</p>
<p>
</p>
<h2>Deliverables</h2>
<p>A. Overall project deliverables</p>
<ol>
<li>
<p>A guide to interpreting the wxWidgets API guide (which is oriented
toward C++ programmers) for Perl programmers.</p>
</li>
<li>
<p>A document listing which wxWidget classes are part of wxPerl, and
which ones aren't.</p>
</li>
<li>
<p>Create screenshots for all Perl-supported wxWidgets, so users can
have more of an idea what each widget is.</p>
</li>
<li>
<p>Create a step-by-step walkthrough for installing wxWidgets and wxPerl
on as many platforms as possible.</p>
</li>
<li>
<p>Convert all wxWidget API docs (oriented toward C++ programmers) to
Perl-oriented documents</p>
</li>
<li>
<p>Review existing tutorials (listed at
<a href="http://wxperl.sourceforge.net/documentation.html):">http://wxperl.sourceforge.net/documentation.html):</a> 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).</p>
</li>
</ol>
<p>B. Phase 1 (2009 Q3) deliverables</p>
<ol>
<li>
<p>100% of item 1 above.</p>
</li>
<li>
<p>100% of item 2 above.</p>
</li>
<li>
<p>80 screenshots of various Wx widgets, plus short accompanying demo
programs that were used to create each.</p>
</li>
<li>
<p>100% of item 4 above.</p>
</li>
<li>
<p>50 wxWidget class API documents rewritten to describe wxPerl interface
instead of wxWidgets interface.</p>
</li>
<li>
<p>0% (yeah, zero) of item 6 above.</p>
</li>
<li>
<p>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.</p>
</li>
</ol>
<p>
</p>
<h2>Project Details</h2>
<p>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.</p>
<p>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.</p>
<p>There are approximately 600 classes described at
<a href="http://docs.wxwidgets.org/2.8.4/wx_contents.html,">http://docs.wxwidgets.org/2.8.4/wx_contents.html,</a> which is the only
class documentation referenced from the project documentation page
<a href="http://wxperl.sourceforge.net/documentation.html.">http://wxperl.sourceforge.net/documentation.html.</a> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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:
<a href="http://www.nntp.perl.org/group/perl.wxperl.users/2009/07/msg6524.html">http://www.nntp.perl.org/group/perl.wxperl.users/2009/07/msg6524.html</a></p>
<p>
</p>
<h2>Inch-stones</h2>
<ol>
<li>
<p>Reinstall wxPerl on at least two of my systems, documenting each
step as I go.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>Write a nice document about which classes are/aren't included; post
this to the wxPerl wiki.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>Write up the results of item 5 as a guide for users.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>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?</p>
</li>
<li>
<p>Begin rewriting the wxWidget (C++-oriented) class documentation to be
wxPerl-oriented.</p>
</li>
<li>
<p>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.</p>
</li>
</ol>
<p>
</p>
<h2>Project Schedule</h2>
<p>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.</p>
<p>
</p>
<h2>Bio</h2>
<p>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.</p>
]]>
Comments (7)
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.
