[gtkmm-documentation] Remove mentions of removed STL-style APIs such as Notebook::pages().

[Murray Cumming <murrayc src gnome org>]

commit a9167915e8ee411acef7fd356d69f2244467e76f
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu Oct 28 16:26:59 2010 +0200

    Remove mentions of removed STL-style APIs such as Notebook::pages().
    
    * docs/tutorial/C/gtkmm-tutorial-in.xml: Remove mention of STL-style API
    that has been removed from gtkmm 3 since the C structs were made private.

 ChangeLog                             |    7 +
 docs/tutorial/C/gtkmm-tutorial-in.xml |  395 ---------------------------------
 2 files changed, 7 insertions(+), 395 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index cab7967..2e896fe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2010-10-28  Murray Cumming  <murrayc murrayc com>
+
+	Remove mentions of removed STL-style APIs such as Notebook::pages().
+
+	* docs/tutorial/C/gtkmm-tutorial-in.xml: Remove mention of STL-style API
+	that has been removed from gtkmm 3 since the C structs were made private.
+
 2010-10-28  Murray Cumming  <murrayc murrayc com>>
 
 	Remove credits mention for removed MSVC 2005 Express section.
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index ac1eade..79d5142 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -1903,364 +1903,6 @@ behaviour. Also, try playing with the options to
 
 </sect2>
 
-<sect2 id="sec-stl-style">
-<title>C++ Standard Library-style APIs</title>
-
-<para>
-If you're an accomplished C++ programmer, you'll be happy to hear that most of
-the &gtkmm; <classname>Container</classname> widgets provide C++ Standard Library-style APIs,
-available via accessor methods, such as
-<methodname>Gtk::Box::children()</methodname> or
-<methodname>Gtk::Notebook::pages()</methodname>. They don't use actual C++ Standard Library
-containers (there are good reasons for this), but they look, feel, and act much
-like regular container classes.
-</para>
-
-<para>These APIs are so similar to C++ Standard Library container APIs that, rather than explaining them in detail, we can refer
-you to the C++ documentation for most of their methods. This is all part of &gtkmm;'s policy of reusing existing standards.
-</para>
-
-<para>
-However, C++ Standard Library-style APIs can require awkward or lengthy code in some situations,
-so some people prefer not to use them, while other people use them religiously.
-Therefore, you are not forced to use them - most container widgets have a
-simpler API, with methods such as <methodname>append()</methodname>
-and <methodname>prepend()</methodname>.
-</para>
-
-<para>
-At a minimum, &gtkmm; container lists support iterators and the usual insertion, deletion, and addition methods.  You can
-always expect the following methods to be available for &gtkmm; C++ Standard Library-style APIs:
-<itemizedlist>
-
-<listitem>
-<para>
-<methodname>begin()</methodname> returns a <literal>begin</literal> iterator
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>end()</methodname> returns an <literal>end</literal> iterator
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>rbegin()</methodname> returns a reverse <literal>begin</literal> iterator
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>rend()</methodname> returns a reverse <literal>end</literal> iterator
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>size()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>max_size()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>empty()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>insert()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>push_front()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>push_back()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>pop_front()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>pop_back()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>clear()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>erase()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>remove()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>find()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>front()</methodname>
-</para>
-</listitem>
-
-<listitem>
-<para>
-<methodname>back()</methodname>
-</para>
-</listitem>
-
-</itemizedlist>
-
-</para>
-
-<para>
-Also, the <literal>[]</literal> operator is overloaded, but that is usually order
-N, so if performance is a consideration, or the list has a large
-number of elements, think carefully before using it.
-</para>
-
-<para>
-The element objects and list objects are defined, for each container, in a
-namespace whose name ends in <literal>_Helpers</literal>.  For example,
-the helper namespace for the notebook widget is
-<classname>Gtk::Notebook_Helpers</classname>.
-</para>
-
-<sect3 id="containers-adding-items">
-<title>Adding items</title>
-<para>
-There is a major difference between &gtkmm; APIs and real C++ Standard Library
-containers.  Normally, when you use a <classname>std::vector</classname>, for
-example, you expect that whatever you put in, you'll get out, unmodified.  You
-wouldn't make a <classname>std::vector&lt;int&gt;</classname> and expect to get
-<literal>double</literal>s out of it.  But, &gtkmm; APIs don't always
-work like that - you will often put one kind of object in, and later get a
-different kind out.  Why this odd behaviour?
-</para>
-
-<para>
-Consider a menu widget, which must maintain a hierarchical list of
-menus and menu items.  Menus can only contain certain objects, such as menu items, separators,
-and submenus.  To ensure consistency, a "filter" is needed to
-keep out illegal objects.  Also, since only a few types of objects are
-allowed, convenience methods can be provided to make it easy to
-build up menus.
-</para>
-
-<para>
-&gtkmm; takes care of both requirements using special
-<emphasis>helper elements</emphasis>.  Helper elements are
-temporary - they're typically constructed and passed to an insertion method in the same call.
- The list insertion method uses the information in the helper element to construct the real
-object, which is then inserted into the container.
-</para>
-
-<para>
-As an example, let's look at the <classname>Notebook</classname> widget
-(explained in the section on <link linkend="sec-notebook">Notebooks</link>).
-<classname>Notebook</classname> widgets contain a series of "pages".
-</para>
-
-<para>
-Each page in a notebook requires, at minimum, the following
-information:
-</para>
-
-<itemizedlist>
-
-<listitem>
-<para>
-A child widget (zero or one), to be placed in the page
-</para>
-</listitem>
-
-<listitem>
-<para>
-A label for the page's tab
-</para>
-</listitem>
-
-</itemizedlist>
-
-<para>
-(The &gtkmm; notebook widget keeps other data for each page as well.)
-</para>
-
-<para>
-To insert a new page in a notebook, we can use one of the notebook
-helper classes, like this:
-</para>
-<programlisting>notebook-&#62;pages().push_back(
-          Gtk::Notebook_Helpers::TabElem(*frame, bufferl));</programlisting>
-
-<para>
-Let's see what's
-going on here.  Assume we have a pointer to a <classname>Notebook</classname>
-widget called <literal>notebook</literal>; we go from that to a member method
-called <methodname>pages()</methodname>, which returns a list object.  On
-this we call the method <methodname>push_back()</methodname> (this should be
-familiar to those who know C++).
-</para>
-
-<para>
-The object that the <methodname>pages()</methodname> method returns is called a
-<classname>Notebook_Helpers::PageList</classname>.  It's one of the
-containers that we keep referring to.  Let's take a look at this class
-(this has been heavily edited for clarity; see
-<filename>&lt;gtkmm/notebook.h&gt;</filename> for the actual definition):
-</para>
-
-<programlisting>namespace Notebook_Helpers
-{
-    class PageList
-    {
-    public:
-             . . .
-        void push_back(const Element&#38; e);
-             . . .
-        Page* operator[](size_type l);
-    };
-};</programlisting>
-
-<para>
-There are two important things to notice here:
-<itemizedlist>
-
-<listitem>
-<para>
-The <methodname>push_back()</methodname> method takes as argument an
-<classname>Element</classname> object (helper);
-</para>
-</listitem>
-
-<listitem>
-<para>
-The overloaded <literal>[]</literal> operator returns a pointer to a
-<classname>Page</classname>.
-</para>
-
-</listitem>
-
-</itemizedlist>
-</para>
-
-<para>
-This scheme has some important advantages:
-</para>
-
-<itemizedlist>
-
-<listitem>
-<para>
-We can provide as many different Helper objects as desired,
-making it simple to construct complex widgets like Menus.
-
-</para>
-</listitem>
-
-<listitem>
-<para>
-Construction of the actual objects can be delayed until an appropriate time. Sometimes we don't have enough information until later
-with GTK+.
-</para>
-</listitem>
-
-<listitem>
-<para>
-The definitions of the objects contained in the list can change; their
-interfaces need not concern the programmer.  For example, even if the
-<classname>Page</classname> object changes drastically, the programmer need not
-be concerned; the <classname>Element</classname>s need not change, and will
-continue to work as expected.
-</para>
-</listitem>
-
-<listitem>
-<para>
-New <classname>Element</classname> objects can be added at any time to support
-new features, without breaking existing code.
-</para>
-</listitem>
-
-</itemizedlist>
-
-<para>
-All multi-item containers have an <classname>Element</classname> object in
-their helper namespaces, and usually there are additional classes available
-(like <classname>TabElem</classname> and <classname>MenuElem</classname>) which
-derive from <classname>Element</classname>.  <classname>Element</classname>
-classes vary from container to container, since each contains different kinds
-of objects.
-</para>
-
-<para>
-It's very important to remember that <classname>Element</classname>s are not
-"real" objects. They exist only temporarily, and they are never stored in the
-container.  They are used <emphasis>only</emphasis> as temporary
-"parameter-holders".  Therefore, the following segment of code is illegal:
-</para>
-<programlisting>MenuElem* m = new MenuElem("hello");
-m-&#62;right_justify();
-items().push_back(*m);</programlisting>
-
-<para>
-We constructed a new <classname>MenuElem</classname> helper object, and then
-tried to invoke <methodname>right_justify()</methodname> on it before adding
-it to the menu.  The trouble is that there is no
-<methodname>right_justify()</methodname> method in the
-<classname>MenuElem</classname> class.  The correct way to accomplish this
-would be:
-</para>
-<programlisting>items().push_back(MenuElem("hello"));
-items().back()-&#62;right_justify();</programlisting>
-
-<para>
-Here, we've constructed a <classname>MenuElem</classname> and inserted it into
-the menu by passing it to <methodname>push_back()</methodname>, causing the
-real menu item to be created.  We've then called
-<methodname>right_justify()</methodname> on the object retrieved from the
-list.  This is correct - the object retrieved from the list is not a
-<classname>MenuElem</classname>, but a real <classname>MenuItem</classname>,
-and therefore supports the <methodname>right_justify()</methodname> method
-as expected.
-</para>
-
-</sect3>
-
-</sect2>
-
 <sect2 id="sec-boxes">
 <title>Boxes</title>
 
@@ -2342,13 +1984,6 @@ The <parameter>padding</parameter> argument specifies the width of an extra
 border area to leave around the packed widget.
 </para>
 
-<para>
-Instead of the <methodname>pack_start()</methodname> and
-<methodname>pack_end()</methodname> methods, you might prefer to use the C++ Standard Library-style
-API, available via the <literal>children</literal> method. See the <link
-    linkend="sec-stl-style">C++ Standard Library-style APIs</link> section for more details.
-</para>
-
 <para><ulink url="&url_refdocs_base_gtk;Box.html">Reference</ulink></para>
 
 </sect4>
@@ -2624,8 +2259,6 @@ To programmatically change the selected page, use the
 <methodname>set_current_page()</methodname> method.
 </para>
 
-<para>There is also an  <link linkend="sec-notebook-stl-style">C++ Standard Library-style API</link> which you might find more obvious.</para>
-
 <para><ulink url="&url_refdocs_base_gtk;Notebook.html">Reference</ulink></para>
 
 <sect3 id="notebook-example"><title>Example</title>
@@ -2641,34 +2274,6 @@ To programmatically change the selected page, use the
 
 </sect3>
 
-<sect3 id="sec-notebook-stl-style">
-<title>C++ Standard Library-style API</title>
-<para>
-The <classname>Gtk::Notebook</classname> widget has a C++ Standard Library-style API, available
-via the <methodname>pages()</methodname> method,  which you might prefer to use to
-add and access pages. See the <link linkend="sec-stl-style">C++ Standard Library-style
-    APIs</link> section for generic information.</para>
-
-<para><ulink url="&url_refdocs_base_gtk;Notebook__Helpers_1_1PageList.html">PageList Reference</ulink></para>
-
-<para>
-To insert pages into a notebook, use the <classname>TabElem</classname> helper
-class, like so:
-</para>
-<programlisting>m_Notebook.pages().push_back(
-    Gtk::Notebook_Helpers::TabElem(m_ChildWidget, "tab 1") );</programlisting>
-
-<para><ulink url="&url_refdocs_base_gtk_html;structGtk_1_1Notebook__Helpers_1_1TabElem.html">TabElem Reference</ulink>.</para>
-
-<para>
-To access an existing child widget, you can call
-<methodname>get_child()</methodname> on one of the <classname>Page</classname> elements
-of the <classname>PageList</classname>:
-</para>
-<programlisting>Gtk::Widget* pWidget = m_Notebook.pages()[2].get_child();</programlisting>
-
-</sect3>
-
 </sect2>
 
 <sect2 id="sec-assistant">