Documentation improvements.

* docs/manual/libsigc_manual.xml: Remove Marshallers section because
it is apparently outdated and there is no example code to test it.
This fixes bug #417924 (Michael Ekstrand)
Also changed LibSigC++ to libsigc++ for consistency.
* sigc++/sigc++.h: Main page text: Rearranged slightly.

3 files changed, 38 insertions, 98 deletions

diff --git a/ChangeLog b/ChangeLog
index 89cd344..01447dc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2010-05-04  Murray Cumming  <murrayc@murrayc.com>
+
+	Documentation improvements.
+	
+	* docs/manual/libsigc_manual.xml: Remove Marshallers section because 
+	it is apparently outdated and there is no example code to test it.
+	This fixes bug #417924 (Michael Ekstrand)
+	* sigc++/sigc++.h: Main page text: Rearranged slightly.
+
 2010-04-27  David King  <davidk@openismus.com>
 
 	Improvements to main page documentation
diff --git a/docs/manual/libsigc_manual.xml b/docs/manual/libsigc_manual.xml
index cb2e84f..bbec28c 100644
--- a/docs/manual/libsigc_manual.xml
+++ b/docs/manual/libsigc_manual.xml
@@ -3,7 +3,7 @@
 <book>
 
 <bookinfo>
-	<title>LibSigC++</title>
+	<title>libsigc++</title>
         <author>
           <firstname>Ainsley</firstname>
           <surname>Pereira</surname>
@@ -12,7 +12,7 @@
 	<pubdate>September 2002. Updated January 2004 by Murray Cumming</pubdate>
 
         <abstract>
-          <para>LibSigC++ is a C++ template library implementing typesafe callbacks. This is an intro to LibSigC++.</para>
+          <para>libsigc++ is a C++ template library implementing typesafe callbacks. This is an intro to libsigc++.</para>
         </abstract>
 </bookinfo>
 
@@ -51,7 +51,7 @@ register_click_handler(okbutton, clicked, somedata);
 	<para>As C++ programmers, we want type safety. We also want to be able to use
 	things other than free-standing functions as callbacks.</para>
 
-	<para>LibSigC++ provides the concept of a slot, which holds a reference to one of
+	<para>libsigc++ provides the concept of a slot, which holds a reference to one of
 	the things that can be used as a callback:
 	<itemizedlist>
 	    <listitem>A free-standing function as in the example</listitem>
@@ -65,7 +65,7 @@ register_click_handler(okbutton, clicked, somedata);
 	<para>To make it easier to construct these, libsigc++ provides the sigc::ptr_fun() and sigc::mem_fun() functions, for creating slots from static functions and member functions, respectively. They return
 	a generic <literal remap="tt">signal::slot</literal> type that can be invoked with <literal remap="tt">emit()</literal> or <literal remap="tt">operator()</literal>.</para>
 
-	<para>For the other side of the fence, LibSigC++ provides <literal remap="tt">signal</literal>s, to which the
+	<para>For the other side of the fence, libsigc++ provides <literal remap="tt">signal</literal>s, to which the
 	client can attach <literal remap="tt">slot</literal>s. When the <literal remap="tt">signal</literal> is emitted, all the connected
 	<literal remap="tt">slot</literal>s are called.</para>
 </sect1>
@@ -80,7 +80,7 @@ register_click_handler(okbutton, clicked, somedata);
 
 	<para>Lets say you and I are writing an application which informs the user when
 	aliens land in the car park. To keep the design nice and clean, and allow for
-	maximum portability to different interfaces, we decide to use LibSigC++ to
+	maximum portability to different interfaces, we decide to use libsigc++ to
 	split the project in two parts.</para>
 
 	<para>I will write the <literal remap="tt">AlienDetector</literal> class, and you will write the code to inform
@@ -126,10 +126,10 @@ int main()
 	are capable of holding any type of callback), so you convert your
 	<literal remap="tt">warn_people()</literal> function to a slot using the <literal remap="tt">slot()</literal> function.</para>
 
-	<para>To compile this example from the downloadable example code, use:</para>
-	<programlisting>g++ example1.cc -o eg1 `pkg-config --cflags --libs sigc++-2.0`</programlisting>
+	<para>To compile this example, use:</para>
+	<programlisting>g++ example1.cc -o example1 `pkg-config --cflags --libs sigc++-2.0`</programlisting>
 	<para>Note that those `` characters are backticks, not single quotes. Run it with</para>
-	<programlisting>./eg1</programlisting>
+	<programlisting>./example1</programlisting>
 	<para>(Try not to panic when the aliens land!)</para>
 
 </sect1>
@@ -313,9 +313,6 @@ int a_return_value;
 
 a_return_value = somesignal.emit();
 </programlisting>
-
-		<para>If you care about every return value things are a little more complicated.
-		See the section on Marshallers for more info.</para>
 </sect1>
 </chapter>
 
@@ -353,7 +350,7 @@ void warn_people_wrapper() // note this is the signature that 'signal_detected'
 </programlisting>
 
 	<para>but after our first million or so we might start looking for a better way. As
-	it happens, LibSigC++ has one.</para>
+	it happens, libsigc++ has one.</para>
 
 <programlisting>
 sigc::bind(slot, arg);
@@ -411,75 +408,6 @@ asignal.connect(  sigc::retype&lt;void, int&gt;( slot(&amp;dostuff) )  );
 	<para>If you only want to change the return type, you can use <literal remap="tt">sigc::retype_return</literal>.
 	<literal remap="tt">retype_return</literal> needs only one template argument.</para>
 </sect1>
-
-<sect1>
-<title>Marshallers</title>
-	<para>When I first mentioned return values, I said that more advanced handling of
-	multiple return values was possible with <literal remap="tt">Marshallers</literal>.</para>
-
-	<para>A Marshaller is a class that gets fed all the return values as they're
-	returned. It can do a couple of things:
-	<itemizedlist>
-	    <listitem>It can stop the emit process at any point, causing no further slots
-	        to be called</listitem>
-	    <listitem>It can return a value, of any type</listitem>
-	</itemizedlist></para>
-
-	<para>For example, if each <literal remap="tt">slot</literal> returned an <literal remap="tt">int</literal>, we could use a marshaller return
-	the average value as a <literal remap="tt">double</literal>. Or we could return all values in a
-	<literal remap="tt">std::vector&lt;int&gt;</literal>, or maybe stop as soon as the first slot returns 5.</para>
-
-	<para>As an example, here's the averaging marshaller:</para>
-
-<programlisting>
-class Averager
-{
-public:
-    // we must typedef InType and OutType for the libsigc++ library
-    typedef double OutType;
-    typedef int InType;
-
-    Averager()
-      : total_(0), number_(0)
-      {}
-
-
-    OutType value() { return (double)total_/(double)number_; } // avoid integer division
-
-    static OutType default_value() { return 0; }
-
-    // This is the function called for each return value.
-    // If it returns 'true' it stops here.
-    bool marshal(InType newval)
-    {
-        total_ += newval; // total of values
-        ++number_;        // count of values
-        return false;     // continue emittion process
-    };
-
-private:
-    int   total_;
-    int   number_;
-};
-</programlisting>
-
-	<para>To use this, we pass the type as an extra template argument when defining
-	the <literal remap="tt">Signal</literal>, eg.</para>
-
-<programlisting>
-sigc::signal&lt;int, Averager&gt; mysignal;
-</programlisting>
-
-	<para>Now we can do:</para>
-<programlisting>
-double average_of_all_connected_slots = mysignal();
-</programlisting>
-
-	<para>Each connected <literal remap="tt">slot</literal> will be called, its value passed to an instance of
-	<literal remap="tt">Averager</literal> and that <literal remap="tt">Averager</literal>'s <literal remap="tt">value()</literal> will be returned.</para>
-
-	<para>In the downloadable examples, this is example6.cc.</para>
-</sect1>
 </chapter>
 
 <chapter id="sec-reference">
diff --git a/sigc++/sigc++.h b/sigc++/sigc++.h
index 7070f9c..19df4f1 100644
--- a/sigc++/sigc++.h
+++ b/sigc++/sigc++.h
@@ -24,28 +24,31 @@
  *
  * @section description Description
  *
- * libsigc++ implements a typesafe callback system for standard C++. It allows
- * you to define signals and to connect those signals to any callback function,
- * either a global or a member function, regardless of whether it is static or
- * virtual. It also contains adaptor classes for connection of dissimilar
- * callbacks and has an ease of use unmatched by other C++ callback libraries.
+ * libsigc++ provides a typesafe (at compile time) callback system for standard 
+ * C++. It allows you to define signals and to connect those signals to any 
+ * callback function, either a global or a member function, regardless of whether 
+ * it is static or virtual. It also contains adaptor classes for connection of 
+ * dissimilar callbacks.
  *
- * For instance, see @ref adaptors "Adaptors", @ref sigcfunctors "Functors",
- * @ref lambdas "Lambdas", @ref signal "Signals" and @ref slot "Slots".
+ * For instance, see the @ref signal "Signals", @ref sigcfunctors "Functors", 
+ * @ref slot "Slots", @ref adaptors "Adaptors", and @ref lambdas "Lambdas".
  *
- * See also <a href="http://libsigc.sourceforge.net/">the libsigc++ website</a>.
+ * See also the 
+ * <a href="http://libsigc.sourceforge.net/libsigc2/docs/manual/html/index.html">libsigc++ tutorial</a>, 
+ * the <a href="http://libsigc.sourceforge.net/">the libsigc++ website</a>, and 
+ * the <a href="http://library.gnome.org/devel/gtkmm-tutorial/unstable/chapter-signals.html">Signals appendix of the Programming with gtkmm book</a>.
  *
  * @section features Features
  *
- * - Compile time typesafe callbacks (faster than run time checks)
- * - Typesafety violations report line number correctly with template names (no
- *   tracing template failures into headers)
+ * - Compile-time typesafe callbacks (also faster than run time checks)
+ * - Type-safety violations report the line number correctly with template names 
+ *   (no tracing template failures into headers)
  * - No compiler extensions or meta compilers required
  * - Proper handling of dynamic objects and signals (deleted objects will not
- *   cause seg faults)
+ *   cause crashes)
  * - Extendable API at any level: signal, slot, connection and trackable
  * - Extensions do not require alteration of basic components
- * - User definable accumulators
+ * - User-definable accumulators
  * - A variety of adaptors to change the callback signature: bind, hide,
  *   retype, compose and lambda call groups
  *
@@ -64,13 +67,13 @@
  *
  * Alternatively, if using autoconf, use the following in @c configure.ac:
  * @code
- * PKG_CHECK_MODULES([LIBSIGCXX], [sigc++-2.0])
+ * PKG_CHECK_MODULES([LIBSIGC], [sigc++-2.0])
  * @endcode
- * Then use the generated @c LIBSIGCXX_CFLAGS and @c LIBSIGCXX_LIBS variables
+ * Then use the generated @c LIBSIGC_CFLAGS and @c LIBSIGC_LIBS variables
  * in the project @c Makefile.am files. For example:
  * @code
- * program_CPPFLAGS = $(LIBSIGCXX_CFLAGS)
- * program_LDADD = $(LIBSIGCXX_LIBS)
+ * program_CPPFLAGS = $(LIBSIGC_CFLAGS)
+ * program_LDADD = $(LIBSIGC_LIBS)
  * @endcode
  */