[pclasses-cvs] pclasses2/doc/manual pclasses2.lyx,1.3,1.4

[stephan b. <sg...@us...>]

Update of /cvsroot/pclasses/pclasses2/doc/manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21304/doc/manual

Modified Files:
	pclasses2.lyx 
Log Message:
Added initial s11n module docs.

Index: pclasses2.lyx
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/doc/manual/pclasses2.lyx,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- pclasses2.lyx	25 Dec 2004 02:38:39 -0000	1.3
+++ pclasses2.lyx	26 Dec 2004 09:37:05 -0000	1.4
@@ -253,6 +253,9 @@
 \layout Itemize
 
 Crypto: cryptography and hasing support.
+\layout Itemize
+
+s11n: object serialization support.
 \layout Section
 
 Core Module
@@ -643,6 +646,104 @@
 WorkQueue
 \layout Section
 
+s11n Module
+\layout Standard
+
+The types in this section all live in the namespace P::s11n.
+\layout Standard
+
+This module is a direct fork/port of s11n.net's libs11n framework.
+ Only the core, non-platform-dependents parts are ported here.
+\layout Standard
+
+P::s11n will not be documented much here, as it is just a clone of libs11n,
+ which already has a 
+\emph on 
+huge
+\emph default 
+ amount of documentation.
+\layout Standard
+
+
+\series bold 
+\emph on 
+\color red
+Caveat and appology
+\series default 
+\emph default 
+\color default
+: as this module is basically a copy/paste operation from the main s11n
+ tree, the classes and namespaces in this module do not conform to P's standard
+ naming conventions.
+ Also, i [stephan] am the maintainer of s11n.net, as well of of P::s11n,
+ and want to keep the cross-tree-porting effort to a minimum.
+ We hope you can appreciate the reasons for this API inconsistency.
+ A more P-friendly interface will be developed at some point, to hide this
+ difference from (most) client code.
+ 
+\layout Subsection
+
+SIO interface
+\layout Standard
+
+Clients using P's s11n features are encourages to use the P::SIO API, provided
+ via 
+\family typewriter 
+<pclasses/s11n/SIO.h>
+\family default 
+.
+\layout Subsection
+
+Registering Serializables
+\layout Standard
+
+See (srcdir)/test/s11nTest.cpp, registrations.cpp, FactoryTest.h and CType.cpp
+ for a complete example of plugging in types to P::s11n.
+\layout Subsection
+
+Loading Serializers
+\layout Standard
+
+For reading s11n data, clients do not need to know the input format or Serialize
+r needed to read it - this is handled automatically by s11n.
+ For output, however, clients must choose a Serializer.
+ Something like this will do the trick:
+\layout Quote
+
+#include <pclasses/s11n/SIO.h> // P client interface into s11n
+\layout Quote
+
+...
+\layout Quote
+
+::P::SIO::SerializerInterface;
+\layout Quote
+
+// NODE_TYPE is an arbitrary s11n-support data node type, like P::s11n::s11n_nod
+e or data_node.
+\layout Quote
+
+// Load it via the plugin manager:
+\layout Quote
+
+SerializerBase * ser = ::P::SIO::createSerializer( "expat" );
+\layout Standard
+
+Of course, 
+\begin_inset Quotes sld
+\end_inset 
+
+expat
+\begin_inset Quotes srd
+\end_inset 
+
+ may be the name of any linked-in or dynamically loadable SerializerBase
+ type.
+\layout Standard
+
+See the file (srctree)/test/s11nTest.cpp for a full example.
+\layout Section
+
 Misc notes
 \layout Subsection