[gtkmm-documentation/wip/dboles/radiobutton-group: 16/16] Redo odd wording @ RadioBut.set_group(get_group())

[Daniel Boles <dboles src gnome org>]

commit 4912f8ca1ccf71fff8167113bc23cf8855f647ec
Author: Daniel Boles <dboles src gmail com>
Date:   Sun Nov 24 19:37:03 2019 +0000

    Redo odd wording @ RadioBut.set_group(get_group())
    
    constness isn't the issue here; rather it is the value class of the
    argument of set_group(). That method needs an lvalue reference as it
    modifies the Group by adding the RadioButton to it. That's why we can't
    `rb2.set_group( rb1.get_group() )`. But we can store the Group returned
    by get_group() in a variable and then pass that to set_group() calls.
    Not that there is much reason to, given join_group(), but it works fine.
    
    Then I got carried away and added a program listing showing it
    working... which, while mostly superfluous, does provide a nice
    opportunity to explain briefly that RadioButtonGroup is a handle type,
    meaning that it can be declared automatically and discarded by RAII
    without worrying about thusly releasing the RadioButtons from itself.
    That then informs readers for the next example that creates a new Group.
    
    This is the first use of either "lvalue" or "rvalue" in the docbook!
    That's either a good thing or a slippery, slippery slope to start on...

 docs/tutorial/C/index-in.docbook | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 3c79c83..e91c7e8 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -1008,10 +1008,33 @@ same group by using <methodname>join_group()</methodname> to tell the other
 </para>
 
 <para>
+The purpose of <methodname>join_group()</methodname> is to make it easier to
+express that you want a given button to use a group established by another.
+There is another way to do this, using <methodname>get_group()</methodname>
+and <methodname>set_group()</methodname>. However, this has a pitfall:
 Note that you can't do
 <programlisting>rb2.set_group(rb1.get_group());</programlisting>
 because <methodname>get_group()</methodname> returns a <classname>RadioButton::Group</classname>
-which is modified by <methodname>set_group()</methodname> and therefore is non-const.
+by value, and an unnamed rvalue cannot be passed as the lvalue reference needed
+by <methodname>set_group()</methodname>. Instead, you must assign the result of
+<methodname>get_group()</methodname> to a variable and pass that to
+<methodname>set_group()</methodname> as an lvalue:
+</para>
+
+<programlisting>
+auto rb1 = Gtk::make_managed&lt;Gtk::RadioButton&gt;("button1");
+auto rb2 = Gtk::make_managed&lt;Gtk::RadioButton&gt;("button2");
+auto rb3 = Gtk::make_managed&lt;Gtk::RadioButton&gt;("button3");
+auto group = rb1-&gt;get_group();
+rb2-&gt;set_group(group);
+rb3-&gt;set_group(group);
+</programlisting>
+
+<para>
+This works because the group is really a handle and therefore can be discarded
+once it has been used to tell the radio buttons to group with each other. Still,
+as <methodname>join_group()</methodname> does the same thing in one less line,
+you might not find much use for this pattern, but it is shown for completeness.
 </para>
 
 <para>