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

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

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

Modified Files:
	pclasses2.lyx 
Log Message:
minor changes/fixed

Index: pclasses2.lyx
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/doc/manual/pclasses2.lyx,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- pclasses2.lyx	29 Dec 2004 20:10:55 -0000	1.5
+++ pclasses2.lyx	18 Jan 2005 18:13:05 -0000	1.6
@@ -43,9 +43,7 @@
 \layout Abstract
 
 This is the library manual for P::Classes 2.x.
-\layout Abstract
-
-It provides an overview of what features P::Classes provides and how to
+ It provides an overview of what features P::Classes provides and how to
  use them.
  This document is a supplement to the API docs, and does not provide a 100%
  standalone source of information about the library.
@@ -93,7 +91,7 @@
 Threading.
 \layout Itemize
 
-Plugins.
+Plugins (dynamic loading of types from DLLs).
 \layout Itemize
 
 Server-neutral database interface, including modules for MySQL(tm), Postgres(tm)
@@ -103,18 +101,25 @@
 Unicode-capable string and regular expressions support.
 \layout Itemize
 
-Signals and slots.
+Generic, type-safe callback (signals and slots).
+\layout Itemize
+
+Application-level services, such as persistant, per-application preferences/conf
+iguration data.
+\layout Itemize
+
+Generic, powerful object serialization.
 \layout Standard
 
 P 
 \begin_inset Quotes sld
 \end_inset 
 
-should run
+should
 \begin_inset Quotes srd
 \end_inset 
 
- at at least the following architectures:
+ run on at least the following architectures:
 \layout Itemize
 
 Win32, MSVC (
@@ -124,7 +129,7 @@
 )
 \layout Itemize
 
-Posix (GNU/Linux), 
+Posix (e.g., GNU/Linux), 
 \color red
 gcc 3.2(?)+
 \layout Itemize
@@ -162,6 +167,26 @@
 pclasses2
 \family default 
 .
+\layout Subsubsection
+
+3rd-party dependencies
+\layout Standard
+
+As of this writing, P2 has the following dependencies on 3rd-party libraries:
+\layout Itemize
+
+zlib
+\layout Itemize
+
+bz2lib
+\layout Itemize
+
+expat (dep to be removed)
+\layout Itemize
+
+Unix systems only: libdl or libltdl, or another supported native interface
+ similar to dlopen().
+ (Windows systems use the built-in LoadModule() function instead.)
 \layout Subsection
 
 Disclaimers
@@ -193,32 +218,46 @@
  Some included source code may fall under other licenses, such as BSD or
  Public Domain.
  Please see the specific files for details.
+ All licenses used in this project allow clients to use the library in their
+ own code without being forced to change their own software's licenses.
 \layout Subsection
 
 Credits
 \layout Itemize
 
-Christian Prochnow: author, project lead and main developer.
+Christian Prochnow (Germany): author, project lead and main developer.
 \layout Itemize
 
-Marc Duerner: 
+Dr.
+ Marc Duerner (Germany): 
 \color red
 TODO
 \color default
 .
 \layout Itemize
 
-Bernhard Rosenkraenzer: 
+Bernhard 
+\begin_inset Quotes sld
+\end_inset 
+
+Bero
+\begin_inset Quotes srd
+\end_inset 
+
+ Rosenkraenzer (Germany): 
 \color red
 TODO
 \color default
 .
 \layout Itemize
 
-Gregor Jehle: w-w-webmaster.
+Gregor Jehle (Germany): w-w-webmaster.
 \layout Itemize
 
-stephan beal: likes to write docs and break old code/conventions.
+Bernhard Hieke (Germany): father figure and a really nice guy.
+\layout Itemize
+
+stephan beal (Germany): likes to write docs and break old code/conventions.
  Writes the P::s11n support (http://s11n.net/ps11n/).
 \layout Section
 
@@ -237,10 +276,13 @@
 Unicode: Unicode string support.
 \layout Itemize
 
+IO: device-independent i/o support.
+\layout Itemize
+
 System: threading and shared library support.
 \layout Itemize
 
-IO: device-independent i/o support.
+XML: Parsers and helpers for working with the world's most Xtreme data format.
 \layout Itemize
 
 Net: network-transparent i/o support.
@@ -249,13 +291,13 @@
 SQL: db-neutral SQL support.
 \layout Itemize
 
-Util: more advanced thread management.
+Util: general utility code.
 \layout Itemize
 
 Crypto: cryptography and hasing support.
 \layout Itemize
 
-s11n: 
+SIO: 
 \begin_inset Quotes sld
 \end_inset 
 
@@ -264,6 +306,9 @@
 \end_inset 
 
  support.
+\layout Itemize
+
+App: application-level services.
 \layout Section
 
 Core Module
@@ -302,6 +347,22 @@
 
 SourceInfo is a type used by Exception to tell developers exactly where
  an exception is thrown from.
+ It is rarely used directly, but is often seen in calls such as this one:
+\layout Quote
+
+throw MyException( 
+\begin_inset Quotes sld
+\end_inset 
+
+Damn!
+\begin_inset Quotes srd
+\end_inset 
+
+, P_SOURCEINFO );
+\layout Standard
+
+where the P_SOURCEINFO macro creates a SourceInfo object to pass to the
+ exception.
 \layout Subsection
 
 LinkedItem
@@ -368,6 +429,8 @@
 The Factory template type plays a major role in P, providing the interface
  for key-based lookup of object factories.
  What does that mean? It means the ability to dynamically load classes.
+ It is based off of the classloading architecture described here: http://s11n.net
+/papers/classloading_cpp.html
 \layout Subsubsection
 
 Registration
@@ -428,7 +491,7 @@
 PFACREG_TYPE_NAME = the string form of the name to use for classloading.
 \layout Itemize
 
-PFACREG_TYPE_INTERFACE = dubtypes of MyType should define this to MyType,
+PFACREG_TYPE_INTERFACE = subtypes of MyType should define this to MyType,
  so that they get registered with the proper base classloader.
 \layout Itemize
 
@@ -437,7 +500,16 @@
 \layout Itemize
 
 PFACREG_CONTEXT = the factory context.
+ 
+\emph on 
+Chefsache
+\emph default 
+.
  Don't set this unless you really, really know what you're doing.
+\layout Standard
+
+As per the general conventions for supermacros, all of these macros are
+ undefined after calling the FactoryReg.h supermacro.
 \layout Paragraph
 
 Factory::registerFactory()
@@ -457,7 +529,7 @@
 \family default 
  or 
 \family typewriter 
-/srctree/test/CType.cpp
+srctree/test/CType.cpp
 \family default 
  for examples.
 \layout Paragraph
@@ -479,7 +551,7 @@
  s11n.
 \layout Subsection
 
-Signals and Slots
+Callback (Signals and Slots)
 \layout Standard
 
 A templates-based, thread-safe signals and slots (object messaging) implementati
@@ -507,6 +579,9 @@
 \layout Standard
 
 Encapsulates a Unicode string.
+ This String type is highly optimized for substring and range operations,
+ allowing several Strings to share parts of a string without copying them
+ (until a copy is needed, of course).
 \layout Subsection
 
 
@@ -609,6 +684,8 @@
 
 Provides a platform-neutral interface into shared libraries (also called
  DLL's and .so's).
+ This includes the ability to open them and peek inside them to extract
+ known symbols.
 \layout Subsubsection
 
 
@@ -733,16 +810,50 @@
 
 \layout Standard
 
-The types in this section all live in the namespace P::Util.
+Most of the types in this section all live in the namespace P::Util, and
+ some live under P::Util::Ext.
+\layout Subsection
+
+SimpleArgvParser
+\layout Standard
+
+A simple helper to parse command-line arguments passed in to main().
+\layout Subsection
+
+SimplePropertyStore
+\layout Standard
+
+A simple key/value pair store.
+\layout Subsection
+
+StringTool
+\layout Standard
+
+A set of utility functions for working with string data.
+\layout Subsection
+
+LexT
+\layout Standard
+
+A type providing a simple-to-use lexical casting interface.
 \layout Subsection
 
 ManagedThread
+\layout Standard
+
+IMO, should be moved to System (stephan).
 \layout Subsection
 
 ThreadPool
+\layout Standard
+
+IMO, should be moved to System (stephan).
 \layout Subsection
 
 WorkQueue
+\layout Standard
+
+IMO, should be moved to System (stephan).
 \layout Section
 
 s11n Module
@@ -758,6 +869,13 @@
 
 This module is a direct fork/port of s11n.net's libs11n framework.
  Only the core, non-platform-dependents parts are ported here.
+ Clients are encouraged to avoid using P::s11n directly, and to use P::SIO
+ (section 
+\begin_inset LatexCommand \ref{sub:SIO-interface}
+
+\end_inset 
+
+) when possible, as SIO provides a P-centric API into the s11n core.
 \layout Standard
 
 P::s11n will not be documented much here, as it is just a clone of libs11n,
@@ -782,9 +900,13 @@
  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.
- 
+ See the P::SIO module (section 
+\begin_inset LatexCommand \ref{sec:IO-Module}
+
+\end_inset 
+
+) for a P-centric s11n API, which uses the P naming conventions and provides
+ s11n proxies for several P types.
 \layout Subsection
 
 SIO interface
@@ -798,9 +920,9 @@
 Clients using P's s11n features are encourages to use the P::SIO API, provided
  via 
 \family typewriter 
-<pclasses/s11n/SIO.h>
+<pclasses/SIO/SIO.h>
 \family default 
-.
+, instead of using P::s11n.
 \layout Standard
 
 Here are examples of using the SIO interface:
@@ -808,7 +930,7 @@
 
 
 \family typewriter 
-#include <pclasses/s11n/SIO.h>
+#include <pclasses/PSIO/SIO.h>
 \layout Quote
 
 
@@ -828,13 +950,11 @@
 
 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.
+ if s11n can find a handler for it, it will be loaded.
 \layout Standard
 
 Loading, method #1:
@@ -913,6 +1033,21 @@
 
 \family typewriter 
 MyType * t = loadSerializable<MyType>( file|stream );
+\layout Standard
+
+As a general tip: use 
+\family typewriter 
+std::auto_ptr<S11nNode>
+\family default 
+ to make sure that 
+\begin_inset Quotes sld
+\end_inset 
+
+temporary
+\begin_inset Quotes srd
+\end_inset 
+
+ nodes are cleaned up in the face of exceptions.
 \layout Subsection
 
 Registering Serializables
@@ -934,7 +1069,7 @@
 
 
 \family typewriter 
-#include <pclasses/s11n/SIO.h> // P client interface into s11n
+#include <pclasses/SIO/SIO.h> // P client interface into s11n
 \layout Quote
 
 
@@ -1027,6 +1162,8 @@
 \family default 
 , to get information regarding includes paths and linker options required
  for building client code.
+ Note that P is separated into several libraries, and the exact libs clients
+ need to link to depends on which parts of P they use.
 \layout Standard