[Mockpp-commits] mockpp/mockpp/docs/en faq.docbook,1.6,1.7 index.docbook,1.27,1.28

[Ewald A. <ewa...@us...>]

Update of /cvsroot/mockpp/mockpp/mockpp/docs/en
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10898/mockpp/docs/en

Modified Files:
	faq.docbook index.docbook 
Log Message:
updated faq

Index: faq.docbook
===================================================================
RCS file: /cvsroot/mockpp/mockpp/mockpp/docs/en/faq.docbook,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- faq.docbook	23 Apr 2005 18:22:28 -0000	1.6
+++ faq.docbook	17 Jun 2005 18:58:36 -0000	1.7
@@ -91,6 +91,104 @@
 
  <!-- -->
 
+
+ <qandaentry>
+  <question>
+   <para>Why does &mockpp; uses that rather complicated <classname>Formatter</classname>
+   class?</para>
+  </question>
+
+  <answer>
+  <para>The two reasons to use this aproach were enhanced readability and
+  better support for internationalisation:</para>
+
+  <para>Simply take the example from the handbook:
+
+  <programlisting>
+
+    Person pers("Bob", 6);
+    String  format = "%4 says: %3 plus %2 gives %1";
+
+    string one = "one";
+    string two = "two";
+    string three = "three";
+
+    format &lt;&lt; three   // %1
+           &lt;&lt; two     // %2
+           &lt;&lt; one     // %3
+           &lt;&lt; pers;   // %4
+
+    std::cout &lt;&lt; format &lt;&lt; std::endl;
+  </programlisting>
+
+  The format string already gives you a good idea about the result, you only
+  have to substitute the <token>%</token> by the actual values.</para>
+
+  <para>Please also understand that I intentionally reverted the order of the
+  <token>%</token>-substitutes to show this possibility. More about the need for
+  this below.</para>
+
+  <para>On the contrary it is far more difficult to understand the outcome with
+  standard streaming operators:
+
+  <programlisting>
+
+    cout &lt;&lt; pers.toString()
+         &lt;&lt; " says: "
+         &lt;&lt; one
+         &lt;&lt; " plus "
+         &lt;&lt; two
+         &lt;&lt; " give "
+         &lt;&lt; three;
+  </programlisting>
+
+  I am pretty sure you will forget the one or the other space which seperates
+  for example the literal "plus" from the variable "two".</para>
+
+
+  <para>The other important point is: you can't translate the second solution reasonably.
+  Translating "says:" and "plus" seperately and concatenating them like above often
+  results in the nonsense you get when you read manuals for devices from
+  the far east. Often also the order of the substituted words change in the
+  translated version. In this case the translator simply would swap <token>%1</token>
+  and <token>%2</token>.</para>
+
+  <para>Maybe you don't find it worth the effort but english is not the only language
+  on earth, so why not prepare a nice way to translate the library?
+  Someone interested in a translated version simply uses <command>xgettext</command>
+  to collect the strings, translates them with a simple editor and replaces macro
+  <function>mockpp_i18n()</function> with the according call from the standard
+  <systemitem class="library">intl</systemitem> package.</para>
+
+  <para>And overloading <function>operator&lt;&lt;</function> is similar to the standard
+  iomanip functions:
+
+  <programlisting>
+
+  class CA
+  {
+    String toString()
+    {
+      ...
+    }
+    ...
+  };
+
+  String &amp; operator &lt;&lt; (String &amp;formatter, const CA &amp;o)
+  {
+    return ::operator&lt;&lt; (formatter, o.toString());
+  }
+  </programlisting>
+
+  Additionally you can use <function>MOCKPP_ENABLE_DEFAULT_FORMATTER</function>
+  to generate a default <function>operator&lt;&lt;</function> which outputs the
+  class name which is often enough.</para>
+
+  </answer>
+ </qandaentry>
+
+ <!-- -->
+
  <qandaentry>
 
   <question>

Index: index.docbook
===================================================================
RCS file: /cvsroot/mockpp/mockpp/mockpp/docs/en/index.docbook,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -d -r1.27 -r1.28
--- index.docbook	30 Apr 2005 21:14:41 -0000	1.27
+++ index.docbook	17 Jun 2005 18:58:36 -0000	1.28
@@ -10,8 +10,8 @@
   <!ENTITY cppunit      '<application>cppunit</application>' >
   <!ENTITY copyyears    '2002-2005'                          >
   <!ENTITY mockpp_email 'mockpp at ewald-arnold dot de'      >
-  <!ENTITY release_date '<date>2005-05-01</date>'            >
-  <!ENTITY release_info '<releaseinfo>1.08.00</releaseinfo>' >
+  <!ENTITY release_date '<date>2005-06-17</date>'            >
+  <!ENTITY release_info '<releaseinfo>1.08.02</releaseinfo>' >
 
   <!ENTITY chap_bookinfo               SYSTEM 'bookinfo.docbook'              >
   <!ENTITY chap_intro                  SYSTEM 'intro.docbook'                 >