Hello everyone,
For some time now, there has been talk of bringing the PHP-GTK
documentation up-to-date. It's a great extension which suffers heavily
from the lack of comprehensive and current documentation.
I've personally been poking at the process for well over a year now, but
have had little success due to the difficulty that exists in recruiting
people into a project which is suffering as it is. There has been a wiki
page on the subject for about as long, available at
http://wiki.php.net/php-gtk/gtkphd.
Having recently taken some time to join the PHP documentation team and
familiarize myself with the documentation system, I'm feeling much more
confident about the prospect of bringing the PHP-GTK documentation into
line with the current documentation system.
I'd like to make a proposal to that effect. I'm requesting that we
create a branch at
http://svn.php.net/repository/phpdoc/doc-base/branches/php-gtk/, as well
as http://svn.php.net/repository/phpdoc/en/branches/php-gtk/.
The former would be to create a temporary fork of the docgen scripts in
order to generate a good set of skeleton documentation for PHP-GTK,
laying it out in a reasonable fashion.
The latter branch would be the second part of the process, which is to
work on adding PHP-GTK's documentation to the main manual, as an
extension. Now, I realize that PHP-GTK seems like an entirely separate
project from the main PHP project, but I think that's simply a matter of
how it's been run until now.
PHP-GTK is, as any other, an extension to PHP. The way it functions may
seem fundamentally different than how PHP itself does, but the reality
is that it's simply creating a loop and interfacing with the GTK
toolkit, as any SAPI might interface with a webserver.
As for the actual structure of this proposed set of documentation within
the main manual, here's what I'm thinking:
PHP-GTK is fundamentally composed of a few different sub-extensions.
There is, of course, the core of the extension, but as in PDO, there are
extensions which add functionality to that.
Each part of PHP-GTK - that is, ATK, GDK, GTK, Pango and so on - would
be a sub-section to the extension's documentation. Since the PHP manual
is very hierarchical as it is, this shouldn't pose any problem at all.
Within each of these subsections, the respective classes would be
listed, and any relevant introduction, as with any extension.
Unique - at least as far as I know - to PHP-GTK, in terms of PHP
extensions, are two constructs.
The first construct, which is very easy to mark up, is GObject
properties. Essentially, these are properties inherited from the GObject
class, which aren't directly available in the scope of the class. They
are accessed via a getter and setter configuration. I'm not certain why
the extension is configured this way, but it probably has something to
do with the way GTK itself is designed.
The second construct is the "signal". These are precisely what they
sound like. The concept exists in other languages, but I don't know of
any other extensions that make use of them. Basically, one connects a
callback to a signal, and that callback is called when the signal is
triggered by an action. That action might be, for instance, a user
clicking a button. I imagine these could be marked up as a variant of
methods.
So, I'm requesting your comments and criticisms on the subject, as well
as requesting that anyone interested in helping pipe up, so I can gauge
how much of this work I would have to do myself.
For quick reference, here's the brass tacks:
* Create two branches; one under doc-base, and one under en.
* Modify docgen to generate skeletons for PHP-GTK - I've already done
most of the work for this already.
* Fill in the documentation, borrowing what we cleanly can from the
existing out-of-date documentation for PHP-GTK.
* Merge the extension's documentation branch into trunk, once it's
reasonably complete.
Thanks,
Justin Martin, a.k.a. FrozenFire
