[gtkmm-documentation/wip/dboles/when-manage-does-not-mean-managed-3] Clarify that user sometimes must delete if managed

[Daniel Boles <dboles src gnome org>]

commit 2a68fab985fbd7c241997bb6d7aa4566462e3187
Author: Daniel Boles <dboles src gmail com>
Date:   Sat Oct 27 13:23:38 2018 +0100

    Clarify that user sometimes must delete if managed
    
    container.ccg remembers whether the object was originally un-floated by
    Gtk::manage() and, if so, restores that state during Container.remove(),
    with the result that the removed widget is *not* deleted, as it would be
    in GTK+, but instead it is re-floated and requires the user to deal with
    (e.g. to add it to some other container or to finally call delete on it)
    
    This is documented in container.hg but nowhere that I can see in our
    tutorial, and I think it is worth mentioning here, since it is not
    completely intuitive: users might otherwise think that the fact manage()
    delegates lifetime management to the Container means they get back the
    same behaviour of C widgets, i.e. that remove() would cause destruction,
    but of course that is not the case, and we might thus encourage leaks.
    
    So mention that manage() only relieves the user of the burden of calling
    delete if they add the widget to a parent and do not remove it later, in
    both the Memory Management section and the part about deleting wrappers.

 docs/tutorial/C/index-in.docbook | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 4323203..6925b81 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -509,7 +509,8 @@ The C++ wrapper shall be explicitly deleted if
 <itemizedlist>
 <listitem><para>it's a widget or other class that inherits from <classname>Gtk::Object</classname>, 
and</para></listitem>
 <listitem><para>the C instance has a floating reference when the wrapper is created, and</para></listitem>
-<listitem><para><function>Gtk::manage()</function> is not called.</para></listitem>
+<listitem><para><function>Gtk::manage()</function> has not been called on it, or</para></listitem>
+<listitem><para><function>Gtk::manage()</function> was called on it, but it was never added to, or was later 
removed from, its parent.</para></listitem>
 </itemizedlist>
 <function>Glib::wrap()</function> binds the C and C++ instances to each other.
 Don't delete the C++ instance before you want the C instance to die.
@@ -6414,11 +6415,11 @@ widget will be destroyed whenever its container is destroyed.
 
 <para>
 &gtkmm; provides the <function>manage()</function> function and
-<methodname>add()</methodname> methods to create and destroy widgets. Every widget
+<methodname>add()</methodname> and similar methods to create and destroy widgets. Every widget
 except a top-level window must be added or packed into a container in order to
 be displayed. The <function>manage()</function> function marks a widget
 so that when the widget is added to a container, the container becomes
-responsible for deleting the widget.
+responsible for deleting the widget, meaning the user no longer needs to do so.
 </para>
 
 <para>
@@ -6435,6 +6436,14 @@ to free the button's memory; its deletion has been delegated to the
 <classname>MyContainer</classname> object.
 </para>
 
+<para>
+Note that if you never added the widget to any parent container, or you did but
+later <methodname>Gtk::Container::remove()</methodname>d it from said parent,
+&gtkmm; restores the widget’s lifetime management to whatever state it had
+before <function>manage()</function> was called, which typically means that the
+responsibility for <literal>delete</literal>ing the widget returns to the user.
+</para>
+
 <para>
 Of course, a top-level container will not be added to another container. The
 programmer is responsible for destroying the top-level container using one of