Reworte part of lifetimes.md.

docs/lifetimes.md

@@ -45,20 +45,20 @@ TODO write this
 
 ### Unix
 
-All GtkWidgets are initially created "floating" (referenceless but unowned). When adding to a GtkContainer, the reference count is increased. When removing from a GtkContainer, the reference count is decreased. When the reference count drops back to zero, the widget is destroyed. Since containers are also widgets, when a container is destroyed, its children are removed.
+GtkWidgets are destroyed with the function `gtk_widget_destroy()`. For a container, which is also a widget, all children of the container at destruction time are also destroyed.
 
-An explicit call to `gtk_widget_destroy()` will immediately destroy the widget regardless of any refcounts. Container removal uses the refcounting functions `g_object_unref()`, not `gtk_widget_destroy()`.
+GtkWidgets also have a reference count. Initially, a GtkWidget starts out as *floating* (referenceless but unowned). Adding a widget to a container removes the floating status and increments the refcount. Removing a widget from a container decreases the reference count (but does NOT destroy the widget in and of itself). Once the referencce count drops back to zero, `gtk_widget_destroy()` is called.
 
-TODO destroy rules are inaccurate
+What does this mean? In the normal case, you create a widget, add it to a container, and add the container to a GtkWindow (also a GtkWidget). Then, when you're done, you simply destroy the GtkWindow, which will destroy the widgets inside.
 
-What these rules mean is that in the general case, you create widgets, add them to containers (which are themselves widgets, including GtkWindow), then destroy the uppermost container in the widget tree (usually a GtkWindow) to trigger the destruction of all the widgets.
+Note that removing a widget from a container does not call `gtk_widget_destroy()`; it merely decrements the reference count of the widget.
 
 TODO describe what we need to do
 TODO remove lifetimes.c?
 
 ### Mac OS X
 
-While Cocoa is a reference-counted object environment, simple reference counting of AppKit objects does not really work, and monitoring reference counts for lifetimes is dicouraged. Why? Strong references that we may not know about (think internal bookkeeping or third-party tools). However, if we pretend these additional references don't exist, the lifetime view beccomes similar to the GTK+ one above.
+While Cocoa is a reference-counted object environment, simple reference counting of AppKit objects does not really work, and monitoring reference counts for lifetimes is dicouraged. Why? Strong references that we may not know about (think internal bookkeeping or third-party tools). However, if we pretend these additional references don't exist, the lifetime view beccomes simple.
 
 When a view is created, it is created in a state where it is initially unowned; the documentation says we have to add it to the view hierarchy before we can use it. When a view is added to a superview, its reference count goes up (*retained*). When a view is removed from its superview, its reference count goes down (*released*). Once this virtual reference count goes to zero, the view is no longer safe to use.