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

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

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

Modified Files:
	pclasses2.lyx 
Log Message:
Mass commit: lots of -l/-L linker changes/fixes.

Index: pclasses2.lyx
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/doc/manual/pclasses2.lyx,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- pclasses2.lyx	26 Dec 2004 09:37:05 -0000	1.4
+++ pclasses2.lyx	29 Dec 2004 20:10:55 -0000	1.5
@@ -255,10 +255,23 @@
 Crypto: cryptography and hasing support.
 \layout Itemize
 
-s11n: object serialization support.
+s11n: 
+\begin_inset Quotes sld
+\end_inset 
+
+extreme serialization
+\begin_inset Quotes srd
+\end_inset 
+
+ support.
 \layout Section
 
 Core Module
+\begin_inset LatexCommand \label{sec:Core-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P.
@@ -300,6 +313,11 @@
 \layout Subsection
 
 Phoenix
+\begin_inset LatexCommand \label{sub:Phoenix}
+
+\end_inset 
+
+
 \layout Standard
 
 A shared object provider, providing 
@@ -340,6 +358,11 @@
 \layout Subsection
 
 Factory
+\begin_inset LatexCommand \label{sub:Factory}
+
+\end_inset 
+
+
 \layout Standard
 
 The Factory template type plays a major role in P, providing the interface
@@ -367,9 +390,13 @@
 Simply do the following:
 \layout Quote
 
+
+\family typewriter 
 #define PFACREG_TYPE MyType
 \layout Quote
 
+
+\family typewriter 
 #define PFACREG_TYPE_NAME 
 \begin_inset Quotes sld
 \end_inset 
@@ -381,6 +408,8 @@
 
 \layout Quote
 
+
+\family typewriter 
 #include <pclasses/FactoryReg.h>
 \layout Standard
 
@@ -431,6 +460,23 @@
 /srctree/test/CType.cpp
 \family default 
  for examples.
+\layout Paragraph
+
+Via P::s11n
+\layout Standard
+
+You do not normally need to register your if you use those types with P::s11n
+ (section 
+\begin_inset LatexCommand \ref{sec:s11n-Module}
+
+\end_inset 
+
+), as s11n already installs factories for it's registered types.
+ There are cases where multiple registrations are useful or required, however.
+\layout Standard
+
+See (srctree)/test/s11nTest.cpp for a complete example of registering with
+ s11n.
 \layout Subsection
 
 Signals and Slots
@@ -441,6 +487,11 @@
 \layout Section
 
 Unicode Module
+\begin_inset LatexCommand \label{sec:Unicode-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P::Unicode.
@@ -467,6 +518,11 @@
 \layout Section
 
 Plugin Module
+\begin_inset LatexCommand \label{sec:Plugin-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P::Plugin.
@@ -504,6 +560,11 @@
 \layout Section
 
 System Module
+\begin_inset LatexCommand \label{sec:System-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P::System.
@@ -531,9 +592,19 @@
 \layout Subsection
 
 Shared libraries
+\begin_inset LatexCommand \label{sub:Shared-libraries}
+
+\end_inset 
+
+
 \layout Subsubsection
 
 SharedLib
+\begin_inset LatexCommand \label{sub:SharedLib}
+
+\end_inset 
+
+
 \layout Standard
 
 Provides a platform-neutral interface into shared libraries (also called
@@ -543,12 +614,22 @@
 
 \family typewriter 
 openSharedLibrary()
+\begin_inset LatexCommand \label{sub:openSharedLibrary()}
+
+\end_inset 
+
+
 \layout Standard
 
 This free function opens a DLL and returns a SharedLibrary handle to it.
 \layout Subsection
 
 Threading
+\begin_inset LatexCommand \label{sub:Threading}
+
+\end_inset 
+
+
 \layout Standard
 
 Provides platform-neutral threading facilities.
@@ -567,18 +648,31 @@
 \layout Section
 
 IO Module
+\begin_inset LatexCommand \label{sec:IO-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P::IO.
 \layout Subsection
 
 IODevice
+\layout Standard
+
+IODevice abstracts basic device-independent i/o operations.
 \layout Subsection
 
 IOHandler
 \layout Section
 
 Net Module
+\begin_inset LatexCommand \label{sec:Net-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P::Net.
@@ -591,6 +685,11 @@
 \layout Section
 
 SQL Module
+\begin_inset LatexCommand \label{sec:SQL-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace 
@@ -615,23 +714,23 @@
 Result
 \layout Section
 
-Signals and Slots Module
-\layout Standard
+Crypto Module
+\begin_inset LatexCommand \label{sec:Crypto-Module}
+
+\end_inset 
 
-The types in this section all live in the namespace 
-\color red
-P::???
-\color default
-.
-\layout Section
 
-Crypto Module
 \layout Standard
 
 The types in this section all live in the namespace P::Crypto.
 \layout Section
 
 Util Module
+\begin_inset LatexCommand \label{sec:Util-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P::Util.
@@ -647,6 +746,11 @@
 \layout Section
 
 s11n Module
+\begin_inset LatexCommand \label{sec:s11n-Module}
+
+\end_inset 
+
+
 \layout Standard
 
 The types in this section all live in the namespace P::s11n.
@@ -684,6 +788,11 @@
 \layout Subsection
 
 SIO interface
+\begin_inset LatexCommand \label{sub:SIO-interface}
+
+\end_inset 
+
+
 \layout Standard
 
 Clients using P's s11n features are encourages to use the P::SIO API, provided
@@ -692,13 +801,126 @@
 <pclasses/s11n/SIO.h>
 \family default 
 .
+\layout Standard
+
+Here are examples of using the SIO interface:
+\layout Quote
+
+
+\family typewriter 
+#include <pclasses/s11n/SIO.h>
+\layout Quote
+
+
+\family typewriter 
+...
+\layout Quote
+
+
+\family typewriter 
+using P::SIO;
+\layout Quote
+
+
+\family typewriter 
+save( obj, string|stream );
+\layout Standard
+
+That saves using the SIO::serializerClass() Serializer, which is set via
+ serializerClass(classname).
+ Default is of course expat, because that's all we have at the moment.
+\layout Standard
+
+Loading has 3 options, shown below.
+ Remember that you don't need to know the input format of a stream/file:
+ any loaded/loadable format will do.
+ That is, if s11n can find a handler for it, it will be loaded.
+\layout Standard
+
+Loading, method #1:
+\layout Quote
+
+
+\family typewriter 
+MyType * t = 0;
+\layout Quote
+
+
+\family typewriter 
+S11nNode * node = loadNode( file|stream );
+\layout Quote
+
+
+\family typewriter 
+if( node ) {
+\begin_deeper 
+\layout Quote
+
+
+\family typewriter 
+t = deserialize<MyType>( *node );
+\layout Quote
+
+
+\family typewriter 
+delete node;
+\end_deeper 
+\layout Quote
+
+
+\family typewriter 
+}
+\layout Standard
+
+Loading, method #2:
+\layout Quote
+
+
+\family typewriter 
+MyType t;
+\layout Quote
+
+
+\family typewriter 
+S11nNode * node = loadNode( file|stream );
+\layout Quote
+
+
+\family typewriter 
+if( node ) {
+\begin_deeper 
+\layout Quote
+
+
+\family typewriter 
+bool worked = deserialize<MyType>( *node, t );
+\layout Quote
+
+
+\family typewriter 
+delete node;
+\end_deeper 
+\layout Quote
+
+
+\family typewriter 
+}
+\layout Standard
+
+Loading, method #3:
+\layout Quote
+
+
+\family typewriter 
+MyType * t = loadSerializable<MyType>( file|stream );
 \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.
+ for complete examples of plugging in types to P::s11n, including using
+ DLLs.
 \layout Subsection
 
 Loading Serializers
@@ -710,23 +932,29 @@
  Something like this will do the trick:
 \layout Quote
 
+
+\family typewriter 
 #include <pclasses/s11n/SIO.h> // P client interface into s11n
 \layout Quote
 
+
+\family typewriter 
 ...
 \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.
+\family typewriter 
+// Load it via the plugin manager:
 \layout Quote
 
-// Load it via the plugin manager:
+
+\family typewriter 
+using namespace P::SIO;
 \layout Quote
 
-SerializerBase * ser = ::P::SIO::createSerializer( "expat" );
+
+\family typewriter 
+SerializerInterface * ser = createSerializer( "expat" );
 \layout Standard
 
 Of course, 
@@ -741,13 +969,18 @@
  type.
 \layout Standard
 
-See the file (srctree)/test/s11nTest.cpp for a full example.
+See the file (srcdir)/test/s11nTest.cpp for a complete example.
 \layout Section
 
 Misc notes
 \layout Subsection
 
 Building client software with this library
+\begin_inset LatexCommand \label{sub:Building-client-software}
+
+\end_inset 
+
+
 \layout Subsubsection
 
 Including P::Classes headers
@@ -767,6 +1000,12 @@
 -I/P/prefix/include
 \family default 
 , then your compiler will find them.
+ As a general rule, code belonging to a sub-namespace contained in P lives
+ in 
+\family typewriter 
+<pclasses/NAMESPACE/...>
+\family default 
+, where NAMESPACE is normally the name of the module.
 \layout Subsubsection
 
 Linking under Microsoft DevStudio