Differences

This shows you the differences between two versions of the page.

--- php-gtk:gtkphd [2009/05/05 21:36] – Page moved from ideas:gtkphd to php-gtk:gtkphd lsmith
+++ php-gtk:gtkphd [2011/02/27 21:35] – Added Book Structure frozenfire
@@ Line 1: / Line 1: @@
-==== PHP-GTK PhD migration ====
+==== Migration to Main Manual ====
-PHP-GTK's docs should be moved to the [[doc:phd|PhD]] rendering system, but it is a fairly large job.
+The PHP-GTK manual will be integrated into the main PHP manual as an extension.
-Would involve
+=== Progress ===
-  - migrating the current documentation to a docbook 5 format
-  - writing a PhD compatible theme to generate documentation
-  - writing a reflection based updater to keep docs up to date with code (parsing signals, methods, properties and updating the xml)
-  - getting autogeneration set up so PHP-GTK docs are generated on a regular basis
-==== Progress ====
+== Stage One ==
-  - Working on a fork of docgen.php to pick up classes, methods and signals
+  - <del>Create branches to phpdoc/doc-base and phpdoc/en</del>
-  - Got appropriate markup for the signals stuff
+  - <del>Patch docgen.php script for PHP-GTK-specific Reflection idiosyncrasies.</del>
-  - Still need a theme, and no doubt other stuff
+  - Create new docgen template set for PHP-GTK. __In Progress__
+    * gtk/book.tpl
+    * gtk/chapter.tpl (GTK+ sub-extensions)
+    * gtk/class.tpl
+      * <del>fields (aka GObject properties)</del>
+      * signals
+    * gtk/configure.tpl
+    * gtk/constants.tpl
+    * gtk/method.tpl
+    * gtk/part.tpl (sub-extension parts)
+    * gtk/reference.tpl
+    * gtk/signal.tpl
+  - Finalize book format
+== Stage Two ==
+  - Copy as much well-formed documentation as possible from the [[http://gtk.php.net/manual/en/|old manual]], without muddying the new format.
+  - Fill in any glaringly-missing documentation
+  - Merge branch into phpdoc/en/trunk/
+=== Branches ===
+[[http://svn.php.net/viewvc/phpdoc/doc-base/branches/gtk-docgen/|phpdoc/doc-base/branches/gtk-docgen/]]: A fork of the docgen scripts to accommodate PHP-GTK's Reflection idiosyncrasies.
+[[http://svn.php.net/viewvc/phpdoc/en/branches/php-gtk/|phpdoc/en/branches/php-gtk/]]: Branching the main manual so that our work on the PHP-GTK book doesn't interfere with "normal operations."
+[[http://svn.php.net/viewvc/phpdoc/modules/doc-gtk/|phpdoc/modules/doc-gtk/]]: Module for checking out PHP-GTK externals into a single working copy.
+=== Reflection Idiosyncrasies ===
+PHP-GTK does not currently have proper Reflection data, beyond regular class->method, and such, linking. This means that the docgen.php script, which relies heavily on Reflection information, does not function properly without modification.
+The current solution to this issue is to utilize the .defs files present in the PHP-GTK extension sources, which themselves establish which classes exist in the extension. This is done by simply reading in all of the .defs files, then regex'ing them for of-object specifications, then running array_unique on the resulting set of class names. This produces a list of all defined classes in PHP-GTK.
+=== PHP-GTK-specific Constructs ===
+PHP-GTK utilizes some constructs that are not present in other extensions; or, at least, are not standard. These need to be marked up specially for PHP-GTK.
+== Fields ==
+Each widget class in PHP-GTK has a set of associated properties which are separate from both its member properties and inherited properties. These "GObject properties" are enumerated using GObject::list_properties(int gtype), where gtype is ClassName::gtype.
+== Signals ==
+Each widget class in PHP-GTK has a set of signals, which are essentially callback names for certain actions. One example is the GtkButton "clicked" signal, which is emitted when a user clicks on that GtkButton widget.
+These signals can simply be marked up as a variant of the method format, as they are primarily callbacks. There are a [[http://gtk.php.net/manual/en/gobject.method.signal_query.php|few bits of information]] that are important to be clearly documented for each signal:
+  * ID
+     Each signal has a signal ID associated with it.
+  * Name
+     Each signal has a name.
+  * Emitting Classes
+     The list of classes which emit that signal
+  * [[http://gtk.php.net/manual/en/gobject.enum.gsignalflags.php|GSignalFlags]]
+     The signal flags are used to specify a signal's behaviour, the overall signal description outlines how the stages of a signal emission occur.
+  * Return Type
+  * Parameters
+     Each signal handler callback accepts certain parameters, which are passed in when called. This is usually at the very least the object which emitted the signal.
+=== Book Structure ===
+  * PHP-GTK (Book)
+    * GTK+ (Part)
+      * ATK (Chapter)
+      * GDK (Chapter)
+      * GTK (Chapter)
+      * Pango (Chapter)
+    * Extra (Part)
+    * [...] (Part)

Differences

Page Tools