[gtkmm-documentation/wip/dboles/formatting-3: 3/8] Update some comments about deprecations

[Daniel Boles <dboles src gnome org>]

commit 90c081ccaf306b32f75c9825e5b486ea77f281fa
Author: Daniel Boles <dboles src gmail com>
Date:   Mon Jan 15 18:53:16 2018 +0000

    Update some comments about deprecations
    
    Gtk::Box is not deprecated, so don't indicate that.
    Advise that the pre-Orientable H/V derived classes should not be used.
    Mention that new deprecations arose in 3 and hence should be avoided.

 docs/tutorial/C/index-in.docbook |   25 +++++++++++++++++++++----
 1 files changed, 21 insertions(+), 4 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index dd2bc2a..eed95a1 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -720,7 +720,13 @@ should ask for <application>gtkmm-3.0</application> rather than
 
 <orderedlist>
 <listitem><simpara><classname>Gtk::AppChooser</classname>, <classname>Gtk::AppChooserButton</classname>, 
<classname>Gtk::AppChooserDialog</classname> allow the user to select an installed application to open a 
particular type of content.</simpara></listitem>
-<listitem><simpara><classname>Gtk::Grid</classname> is a new container widget that will eventually replace 
<classname>Gtk::Box</classname> and <classname>Gtk::Table</classname>. It arranges its children according to 
properties of those children rather than its own layout details.</simpara></listitem>
+<listitem><simpara><classname>Gtk::Grid</classname> is a new container widget,
+which you should use to replace the deprecated
+<classname>Gtk::Table</classname>. Also, in some cases, you may find a Grid
+easier to use than one or more <classname>Gtk::Box</classname> instances,
+although that class is not deprecated. <classname>Gtk::Grid</classname> arranges
+its children according to properties of those children rather than its own
+layout details.</simpara></listitem>
 <listitem><simpara><classname>Gtk::Switch</classname> displays On/Off states more explictly than 
<classname>Gtk::CheckBox</classname>. It may be useful, for instance, when allowing users to activate 
hardware.</simpara></listitem>
 </orderedlist>
 
@@ -737,8 +743,16 @@ should ask for <application>gtkmm-3.0</application> rather than
 
 <listitem><simpara><classname>Gtk::Adjustment</classname> and <classname>IconSet</classname> and 
<classname>Gdk::Cursor</classname> are now used via <classname>Glib::RefPtr</classname>.</simpara></listitem>
 
-<listitem><simpara><classname>Gtk::Box</classname>, <classname>Gtk::ButtonBox</classname>, 
<classname>Gtk::IconView</classname>, <classname>Gtk::Paned</classname>, 
<classname>Gtk::ProgressBar</classname>, <classname>Gtk::ScaleButton</classname>, 
<classname>Gtk::Scrollbar</classname> and <classname>Gtk::Separator</classname> now derive from 
<classname>Gtk::Orientable</classname>, allowing their
-orientation (vertical or horizontal) to be specified without requiring the use of a derived class such as 
<classname>Gtk::HBox</classname>.</simpara></listitem>
+<listitem><simpara><classname>Gtk::Box</classname>,
+<classname>Gtk::ButtonBox</classname>, <classname>Gtk::IconView</classname>,
+<classname>Gtk::Paned</classname>, <classname>Gtk::ProgressBar</classname>,
+<classname>Gtk::ScaleButton</classname>, <classname>Gtk::Scrollbar</classname>
+and <classname>Gtk::Separator</classname> now derive from
+<classname>Gtk::Orientable</classname>, allowing their orientation (vertical or
+horizontal) to be specified without requiring the use of a derived class such as
+<classname>Gtk::HBox</classname>. You should not use the old derived classes
+with H or V at the beginning of their name, as they are deprecated and will be
+removed in a future version of GTK+/&gtkmm;.</simpara></listitem>
 
 <listitem><simpara><classname>Gtk::IconView</classname>,
 <classname>Gtk::TextView</classname>, <classname>Gtk::TreeView</classname> and
@@ -768,7 +782,10 @@ the API clearer.</simpara></listitem>
 </orderedlist>
 </para>
 
-<para>All deprecated API was removed in &gtkmm; 3.0, though there will be new deprecations in future 
versions.</para>
+<para>All API that was deprecated during the GTK+ 2 cycle was removed in &gtkmm;
+3.0, though there have been new deprecations in the GTK+ 3 cycle, so you should
+keep an eye out for those in &gtkmm; and use the recommended alternatives in any
+new code.</para>
 
 <para>As a first step to porting your source code to the
 <application>gtkmm-3.0</application> API, you should probably ensure that your