From da7656a43a51f12e8f4c065987013be6fa85e969 Mon Sep 17 00:00:00 2001
From: Casey DeLorme <CDeLorme@gmail.com>
Date: Wed, 14 Aug 2013 16:25:37 -0400
Subject: [PATCH] Updated readme to reflect Gtk3 instructions.

Updated the html readme that accompanies the markdown.
---
 README.html | 39 +++++++++++++++++++++++++++++++++------
 README.md   | 46 +++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 76 insertions(+), 9 deletions(-)
diff --git a/README.html b/README.html
index ef27b28..664e3f4 100644
--- a/README.html
+++ b/README.html
@@ -1,4 +1,3 @@
-
 <html><meta charset="UTF-8"><style>html {
     font-size: 100%;
     overflow-y: scroll;
@@ -98,13 +97,13 @@ <h2>File Hierarchy</h2>
 <ul>
 <li>activity/<ul>
 <li>activity.info</li>
-<li>activity-icon.svg</li>
+<li>icon.svg</li>
 </ul>
 </li>
 <li>activity.py</li>
 <li>setup.py</li>
 </ul>
-<p><em>This activity does not include an <code>activity-icon.svg</code>.  You must build (or extend) the <code>activity.py</code> file.  Changes to the <code>activity.py</code> file must be accomodated by changes to the <code>activity.info</code>.  You will use the <code>setup.py</code> file to create a <code>.xo</code> file later.</em></p>
+<p><em>This activity includes an empty icon named <code>exampleicon.svg</code>.  It is advised that you create your own icon.  You must build (or extend) the <code>activity.py</code> file.  Changes to the <code>activity.py</code> file must be accomodated by changes to the <code>activity.info</code>.  You will use the <code>setup.py</code> file to create a <code>.xo</code> file later.</em></p>
 <h3>Included in This QuickStart</h3>
 <ul>
 <li>/activity<ul>
@@ -258,11 +257,39 @@ <h2>Building &amp; Distributing</h2>
 <p><strong>If your activity does not appear on the desktop after you have installed it, check the activity list, and check your <code>activity.info</code> file for invalid values.</strong></p>
 <h2>GTK and Interfaces</h2>
 <p>Sugar has migrated to Gtk3, which uses GObject Introspection.</p>
-<p>While this sounds complex, what it means is that the new library of code describes itself, and is used to automatically generate 100% accurate documentation.  Unfortunately, this documentation is currently only written in C, so you may have to read C documentation to build with python Gtk3.</p>
-<p>This can be a bit tricky, but hopefully the tips here will help new developers going forward.</p>
-<p>First, sugar has changed the Gtk3 compatible import to sugar3, which means imports from the sugar libraries should have the sugar3 prefix.</p>
+<p>Introspection gives objects the ability to describe themselves, and this means new code can automatically generate accurate documentation at build time.  This means no manual documentation is needed, and no human errors exist in documentation that do not exist in the code.</p>
+<p>Unfortunately since the source is written in C, the documentation is also for the C libraries.  Translating from C to the python API is a bit of a chore, so this section is here to help.</p>
+<p>Let's start with some helpful reference sites:</p>
+<ul>
+<li><a href="http://python-gtk-3-tutorial.readthedocs.org/en/latest/">Python Gtk3 Examples</a></li>
+<li><a href="https://developer.gnome.org/gtk3/3.0/">Gtk3 Documentation</a></li>
+</ul>
+<p>The examples are not complete or comprehensive, but they explain a large portion of commonly used elements and are a good place to start if you are beginning.  The documentation is in C, but translating from the C documentation to python is very strait forward, as it has its own rules.</p>
+<p>You can also make life easier using a python interpreter such as <a href="http://bpython-interpreter.org/">bpython</a> which uses the introspection to provide auto-complete options.  This can be of great help when you are unsure as to a method name, since you can get a list of names automatically.  You can install bpython from yum (or aptitude).</p>
+<p>The first major change, any time you see a sugar import it should be <code>sugar3</code>, as this is the new library that uses Gtk3 elements.</p>
 <p>Second, all of the GObject libraries are imported through the <code>gi.repository</code> library.</p>
 <p><em>Note: The sugar3.activity.Activity extends Gtk.Window, which means if you want to test a software outside sugar you can (mostly) swap in Gtk.Window where the class extends sugar3.activity.Activity.</em></p>
+<p>Now to guide you through reading Gtk3 documentation, remembering that our goal is to translate from C to Python.</p>
+<p>The documentation prefixes all elements with Gtk, for example GtkWindow in the documentation.  This is a <code>Gtk.Window()</code> object in python.</p>
+<p>If you go to the <a href="https://developer.gnome.org/gtk3/3.0/GtkWindow.html">GtkWindow</a> documentation, you will see a menu at the top of the page.  Important sections include:</p>
+<ul>
+<li>Object Hierarchy</li>
+<li>Properties</li>
+<li>Signals</li>
+</ul>
+<p>The others are still valuable, and it starts by providing the list of methods available, but these three are the ones we really want to pay attention to.</p>
+<p>Gtk elements extend from GObject, and each layer inherits the parents properties chained upstream.  This means GtkWindow also has all of the properties, methods, and signals that belong to GtkBin, which means it also gets the same from GtkContainer, up to GtkWidget, and so on.</p>
+<p>This is important, because you will often be searching for a signal or property that may not exist on the child, but belongs to the parent.  So your first lookout: <strong>If you cannot find a property, method, or signal on the element, check its parent elements</strong>.</p>
+<p>As for the methods, the C naming style accepts the element as the first argument, they do not chain off the element as seen in other languages.  So when you see a method such as <code>gtk_window_set_title</code> what that becomes in python is <code>set_title</code>, and you would use it as follows:</p>
+<pre><code>window = Gtk.Window()
+window.set_title("A Title")
+</code></pre>
+<p>Alternatively, if you check the properties you will see <code>title</code> is a property, and you can set them on initialization like this instead:</p>
+<pre><code>window = Gtk.Window(title="A Title")
+</code></pre>
+<p>Which will produce the same window as in the first example.  Now for your second lookout: <strong>Properties with a hyphen (-) become an underscore.</strong>  If you convert hyphens to underscores you can set the properties in the constructor in python.</p>
+<p>The final stage is the signals.  Signals are fired and can be connected to methods, this is the event handling of C and Python.  For example, you can have a method run to scale fonts in the GtkWindow using the <code>check-resize</code> signal, which actually belongs to <a href="https://developer.gnome.org/gtk3/3.0/GtkContainer.html#GtkContainer.signals">GtkContainer</a>, a parent property (<em>First Lookout</em>).</p>
+<p>This is about all the major bumps in the road you can expect to run into, just remember to watch out for parent elements, and conversion rules for properties and methods and you should have an easy time of developing in Gtk3 for Python.</p>
 <h2>Multi-Lingual Development</h2>
 <p>When you run <code>./setup.py genpot</code> this parses your software for any strings wrapped with gettext, and generates a <code>.po</code> file.  This <code>.po</code> file can then be sent out for translation.</p>
 <pre><code>PENDING FURTHER INSTRUCTIONS
diff --git a/README.md b/README.md
index 750dfd8..0fac73f 100644
--- a/README.md
+++ b/README.md
@@ -207,16 +207,56 @@ A symlink only has to be created once, but you should run these two commands fir
 
 Sugar has migrated to Gtk3, which uses GObject Introspection.
 
-While this sounds complex, what it means is that the new library of code describes itself, and is used to automatically generate 100% accurate documentation.  Unfortunately, this documentation is currently only written in C, so you may have to read C documentation to build with python Gtk3.
+Introspection gives objects the ability to describe themselves, and this means new code can automatically generate accurate documentation at build time.  This means no manual documentation is needed, and no human errors exist in documentation that do not exist in the code.
 
-This can be a bit tricky, but hopefully the tips here will help new developers going forward.
+Unfortunately since the source is written in C, the documentation is also for the C libraries.  Translating from C to the python API is a bit of a chore, so this section is here to help.
 
-First, sugar has changed the Gtk3 compatible import to sugar3, which means imports from the sugar libraries should have the sugar3 prefix.
+Let's start with some helpful reference sites:
+
+- [Python Gtk3 Examples](http://python-gtk-3-tutorial.readthedocs.org/en/latest/)
+- [Gtk3 Documentation](https://developer.gnome.org/gtk3/3.0/)
+
+The examples are not complete or comprehensive, but they explain a large portion of commonly used elements and are a good place to start if you are beginning.  The documentation is in C, but translating from the C documentation to python is very strait forward, as it has its own rules.
+
+You can also make life easier using a python interpreter such as [bpython](http://bpython-interpreter.org/) which uses the introspection to provide auto-complete options.  This can be of great help when you are unsure as to a method name, since you can get a list of names automatically.  You can install bpython from yum (or aptitude).
+
+The first major change, any time you see a sugar import it should be `sugar3`, as this is the new library that uses Gtk3 elements.
 
 Second, all of the GObject libraries are imported through the `gi.repository` library.
 
 _Note: The sugar3.activity.Activity extends Gtk.Window, which means if you want to test a software outside sugar you can (mostly) swap in Gtk.Window where the class extends sugar3.activity.Activity._
 
+Now to guide you through reading Gtk3 documentation, remembering that our goal is to translate from C to Python.
+
+The documentation prefixes all elements with Gtk, for example GtkWindow in the documentation.  This is a `Gtk.Window()` object in python.
+
+If you go to the [GtkWindow](https://developer.gnome.org/gtk3/3.0/GtkWindow.html) documentation, you will see a menu at the top of the page.  Important sections include:
+
+- Object Hierarchy
+- Properties
+- Signals
+
+The others are still valuable, and it starts by providing the list of methods available, but these three are the ones we really want to pay attention to.
+
+Gtk elements extend from GObject, and each layer inherits the parents properties chained upstream.  This means GtkWindow also has all of the properties, methods, and signals that belong to GtkBin, which means it also gets the same from GtkContainer, up to GtkWidget, and so on.
+
+This is important, because you will often be searching for a signal or property that may not exist on the child, but belongs to the parent.  So your first lookout: **If you cannot find a property, method, or signal on the element, check its parent elements**.
+
+As for the methods, the C naming style accepts the element as the first argument, they do not chain off the element as seen in other languages.  So when you see a method such as `gtk_window_set_title` what that becomes in python is `set_title`, and you would use it as follows:
+
+    window = Gtk.Window()
+    window.set_title("A Title")
+
+Alternatively, if you check the properties you will see `title` is a property, and you can set them on initialization like this instead:
+
+    window = Gtk.Window(title="A Title")
+
+Which will produce the same window as in the first example.  Now for your second lookout: **Properties with a hyphen (-) become an underscore.**  If you convert hyphens to underscores you can set the properties in the constructor in python.
+
+The final stage is the signals.  Signals are fired and can be connected to methods, this is the event handling of C and Python.  For example, you can have a method run to scale fonts in the GtkWindow using the `check-resize` signal, which actually belongs to [GtkContainer](https://developer.gnome.org/gtk3/3.0/GtkContainer.html#GtkContainer.signals), a parent property (_First Lookout_).
+
+This is about all the major bumps in the road you can expect to run into, just remember to watch out for parent elements, and conversion rules for properties and methods and you should have an easy time of developing in Gtk3 for Python.
+
 
 ## Multi-Lingual Development
 
