Improve docs.

* doc/Makefile.am (smap_TEXINFOS): Add debugcat.texi.
(EXTRA_DIST): Add smapflow.* files.
* doc/smapflow.txt: New file.
* doc/smapflow.fig: New file.
* doc/smapflow.png: New file.
* doc/smapflow.eps: New file.

* doc/smap.texi: Write some sections.
* doc/.gitignore: Add pdf and ps files.

* src/smapd.c (smap_daemon): Fix exit code.

8 files changed, 895 insertions, 7 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
index 5d01164..d44701c 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -20,3 +20,5 @@ smap.ps
 smap.toc
 smap.tp
 smap.vr
+smap.pdf
+smap.ps
diff --git a/doc/Makefile.am b/doc/Makefile.am
index dcd824a..561e22f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -17,12 +17,17 @@
 info_TEXINFOS=smap.texi
 smap_TEXINFOS=\
  fdl.texi\
- sockmap.texi
+ sockmap.texi\
+ debugcat.texi
 
 EXTRA_DIST = \
  gendocs_template\
  mastermenu.el\
- untabify.el
+ untabify.el\
+ smapflow.txt\
+ smapflow.fig\
+ smapflow.png\
+ smapflow.eps
 
 clean-local:
 	@rm -rf manual
diff --git a/doc/debugcat.texi b/doc/debugcat.texi
new file mode 100644
index 0000000..5bafb84
--- /dev/null
+++ b/doc/debugcat.texi
@@ -0,0 +1,43 @@
+@c This file is part of the Smap manual.
+@c Copyright (C) 2010 Sergey Poznyakoff
+@c See file smap.texi for copying conditions.
+@c *******************************************************************
+The following table describes the debug categories available in the
+@command{smapd} server (@pxref{debugging}).  For each category, the
+table gives its symbolic name, ordinal number (in parentheses), and
+a short description.
+
+Particular modules may define their own debug categories.
+
+@table @asis
+@item smap (0)
+Man smap functionality.  Level @samp{1} includes some mild warnings,
+like, e.g. @samp{ignoring master privilege settings}.
+
+Level @samp{10} enables detailed protocol traces, which look like:
+
+@example
+C: 22:mailertable foobar.net,
+S: 19:OK local:foobar.net,
+@end example
+
+@item srvman (1)
+Server manager, i.e. routines responsible for spawning children
+processes, controlling their number and lifetime, etc.
+
+Level @samp{1} gives additional information about allowed connections
+and children exit codes.
+
+Level @samp{2} gives insight to the server manager life cycle.
+
+@item module (2)
+Module subsystem: shows what modules and with what arguments are
+loaded, etc.
+
+@item database (3)
+Databases and their functionality.
+
+@item query (4)
+Query routing.
+@end table
+
diff --git a/doc/smap.texi b/doc/smap.texi
index 59073ac..537ccad 100644
--- a/doc/smap.texi
+++ b/doc/smap.texi
@@ -1,5 +1,4 @@
-\input texinfo @c -*-texinfo-*-
-@smallbook
+@\input texinfo @c -*-texinfo-*-
 @c %**start of header
 @setfilename smap.info
 @settitle Smap Manual
@@ -24,11 +23,11 @@
 @include version.texi
 
 @ifinfo
-@dircategory Individual utilities
+@dircategory Email
 @direntry
 * Smap::                    Socket map framework.
-@c * smapd::                   Socket map daemon.
-@c * smapc::                   Socket map client.
+* smapd: (smap) smapd.      Socket map server.
+* smapc: (smap) smapc.      Socket map client.
 @end direntry
 @end ifinfo
 
@@ -74,14 +73,36 @@ documents Smap @value{VERSION}.
 @menu
 * Intro::                Introduction
 * Overview::             Overview of the Smap Architecture
+* smapd::                Socket Map Server
+* smapc::                Socket Map Client
 * Reporting Bugs::       How to Report a Bug
 
 Appendices
 
 * Protocol::             The Sockmap Protocol
+* Debug Categories::     Debug Categories
 * Copying This Manual::  The GNU Free Documentation License
 * Concept Index::        Index of Concepts
 
+@detailmenu
+ --- The Detailed Node Listing ---
+
+The Socket Map Server
+
+* operation modes::  Smapd Operation Modes.
+* logging::
+* debugging::        Tracing and Debugging.
+* options-smapd::    Command Line Syntax.
+* config-smapd::     Smapd Configuration File.
+* exit codes::       Smapd Exit Codes.
+
+The Sockmap Protocol
+
+* Sendmail Status Codes::
+* MeTA1 Status Codes::
+* Mailfromd Status Codes::
+
+@end detailmenu
 @end menu
 
 @node Intro
@@ -155,8 +176,429 @@ flexible general-purpose mail filter.
 
 @node Overview
 @chapter Overview of the Smap Architecture
+@cindex smap architecture
+  The Smap server consists of the following conceptual parts:
+@command{smapd} daemon, map modules and databases.
+
+@table @dfn
+@cindex @command{smapd}
+@item @command{smapd} daemon
+The @command{smapd} daemon is the principal part of the system.  It
+is responsible for handling incoming connections and dispatching socket
+map requests to appropriate modules.
+
+@cindex module, defined
+@item Map modules
+These are external loadable libraries which contain backend-specific
+lookup drivers. For example, one module may provide a driver for
+lookups in plaintext files, another one may handle DBM lookups and yet
+another -- searches in MySQL databases.  Notice, that modules provide
+abstract drivers, in the sense that they are not bound for look ups
+in particular disk files or databases.  This specific information
+is supplied by @dfn{databases}.
+
+@cindex database, defined
+@item Databases
+A @dfn{database} is an intermediate logical entity associated with a
+particular module.  The database provides actual configuration for the
+module.  Several different databases may be associated with the same
+module, thereby creating several instances of the same lookup driver.
+@end table
+
+  The relationships before these parts are shown in the figure below:
+
+@float Figure, smap-flow
+@caption{Smap Control Flow}
+@center @image{smapflow,,,[ Smap Control Flow ],} 
+@end float
+
+  Here, the @command{smapd} daemon is configured with six databases
+(shown as @dfn{Db a} through @dfn{Db f}), interfacing to three
+different modules (boxes @dfn{Mod A} through @dfn{Mod C}).  The
+databases @samp{a} and @samp{b} interface to module @samp{A},
+databases @samp{c}, @samp{d} and @samp{e} iterface to module @samp{B},
+and database @samp{f} interfaces to module @samp{B}.  All three
+modules are linked with the @file{libsmap} library.
 
+@ifinfo
+@set REQSTYLE double-dashed
+@set REPLSTYLE double-dotted
+@end ifinfo
+@ifnotinfo
+@set REQSTYLE dashed
+@set REPLSTYLE dot-dashed
+@end ifnotinfo
+  The box labeled @samp{CLIENT} represents a client program.  When
+@command{smapd} receives a request from client (its path is shown
+as a @value{REQSTYLE} line), it uses a set of @dfn{routing rules} (see
+the @samp{RR} box on the figure above) to route it to the appropriate
+database.  This database (@samp{Db b}, on the figure) is used to
+pass the request to the underlying module (@samp{Mod A}).  The module,
+after performing a look-up, sends the response back to the client (the
+@value{REPLSTYLE} line on the figure), using interface functions
+from @file{libsmap}.  The latter is responsible for formatting the
+answer in accordance with the socket map protocol.
+
+@cindex default reply
+@cindex reply, default
+  If the request matches no database, the server sends a default
+@samp{NOTFOUND} reply back to the client.
+
+@cindex routing rule, overview
+  Routing rules mentioned above are supplied by the user in the
+@command{smapd} configuration file.  They resemble access control
+lists: each rule consists of a @dfn{condition} and @dfn{destination}.
+The condition may use various data from the connection and request
+itself, such as client IP address or map name from the request, and
+compare them with some static data. If the condition yields true, the
+destination part of the rule points to the database which will handle
+this request.
+
+@node smapd
+@chapter The Socket Map Server
+  Socket map server @command{smapd} is the main part of the package.
+When invoked, it reads the @dfn{configuration file} and parses its
+command line to determine its configuration settings.  Command line
+settings override ones from the configuration file.  The default
+configuration file is @file{/etc/smapd.conf}@footnote{To be precise,
+it is @file{@var{sysconfdir}/smapd.conf}, where @var{sysconfdir} is
+the name of @dfn{system configuration directory}, determined when
+configuring the package. The two most frequently used values for it
+are @file{/etc} and @file{/usr/local/etc}.}  After that,
+@command{smapd} loads the requested modules and starts operation.
+
+  In this chapter we will describe the server operation in detail.
+The discussion below will often refer to @dfn{command line options}
+and @dfn{configuration statements}, so we'll first describe shortly
+what are those.  The formal description will be given later.
+
+  Command line options have two forms.  In @dfn{traditional}, or
+@dfn{short} form, an option is a letter prefixed by a dash (e.g.
+@option{-f}).  In @dfn{long} form, an option consists of two dashes and
+option name (e.g. @option{--foreground}).  Both option forms allow for
+an argument.  For more information on option syntax, see @ref{options-smapd}.
+
+  Configuration file uses the traditional UNIX syntax.  Each statement
+occupies a single line.  Very long lines may be split into several
+physical lines by ending each one with a backslash character.
+Comments are introduced with the @samp{#} character: the character
+itself and everything after it up to next newline is ignored.  For a
+detailed description, see @ref{config-smapd}.
+
+  You can instruct @command{smapd} to read an alternative
+configuration file instead of the default one.  It may be necessaty,
+for example, to test a new configuration.  To do so, use the
+@option{--config=@var{file}} (@option{-c @var{file}}) command line
+option.  Its argument specifies the file name to read, e.g.:
+
+@example
+$ smapd -c ./mysmapd.conf
+@end example
+
+  To check whether your configuration is error-free, use the
+@option{--lint} (@option{-t}) option.  It instructs @command{smapd} to
+parse the configuration file and exit after that.  Any errors found
+are reported on the standard error.  The exit code is @samp{0} if the file
+parsed without errors and @samp{78} otherwise (@pxref{exit codes}, for
+a full list of exit codes).  For example:
+
+@example
+$ smapd -t
+@end example
+
+  Of course, the two options may be used together:
+
+@example
+$ smapd -t -c ./mysmapd.conf
+@end example
+
+@noindent
+or, in long form:
+
+@example
+$ smapd --lint --config ./mysmapd.conf
+@end example
 
+@menu
+* operation modes::  Smapd Operation Modes.
+* logging::
+* debugging::        Tracing and Debugging.
+* options-smapd::    Command Line Syntax.
+* config-smapd::     Smapd Configuration File.
+* exit codes::       Smapd Exit Codes.
+@end menu
+
+@node operation modes
+@section Smapd Operation Modes
+@cindex operaton modes
+@cindex modes, operation
+@cindex standalone mode
+@cindex mode, standalone
+  There are two modes of operation.  In @dfn{standalone} mode,
+@command{smapd} detaches itself from the terminal and listens on
+incoming requests in background.  In other words, it becomes a
+@dfn{daemon}.  When a connection arrives, the server spawns a copy
+of itself (called @dfn{child process}) to handle it.  Thus, a number
+of incoming connections are handled in parallel.  This is the default
+mode.
+
+@cindex inetd mode
+@cindex mode, inetd
+@anchor{inetd-mode}
+  In @dfn{inetd} mode, @command{smapd} does not listen on network
+addresses nor becomes a daemon.  Instead, it reads requests from its
+standard input and sends replies on its standard output.  As its name
+implies, this mode is intended for use from the @file{inetd.conf}
+file.
+
+  The inetd mode is requested from command line using the
+@option{--inetd} (@option{-i}) option, or from configuration file,
+using @samp{inet-mode yes} statement.
+
+@node logging
+@section Logging
+@cindex logging
+@cindex diagnostics
+  The server determines automatically where its diagnostics output
+should go.  By default, it goes to standard error.  However, after
+detaching from the terminal in standalone mode, @command{smapd}
+sends diagnostics to syslog, using facility @samp{daemon} by default.
+The same apllies also if its standard input is not attached to a
+terminal.
+
+  Two command line options are provided to manually alter these
+defaults.  The @option{--stderr} (@option{-e}) option instructs
+@command{smapd} to always send its diagnostics to the standard error,
+In contrast, the @option{--syslog} (@option{-l}) option forces it
+to use syslog.
+
+  The log facility can be changed in configuration file, using the
+@samp{log-facility} statement (FIXME-pxref), or in the command line,
+using the @option{--log-facility} (@option{-F}) option.  In both
+cases, the argument is the facility number or symbolic name.  Valid
+names are: @samp{user}, @samp{daemon}, @samp{auth}, @samp{authpriv},
+@samp{mail}, @samp{cron}, and @samp{local0} through @samp{local7}.
+
+  Similarly, the log tag can also be changed, either from the
+configuration file, using the @samp{log-tag} statement, or from the
+command line, using the @option{--log-tag} (@option{-L}) option,
+
+@node debugging
+@section Tracing and Debugging
+  The amount of information logged by the server is configurable.
+By default, it is quite silent and outputs only diagnostics
+that call to special attention, such as errors and the like.  You may
+request more information, however.  For further discussion, it is
+convenient to introduce two main information groups: query traces and
+debugging information.  @dfn{Query traces} are log messages that show
+received queries and corresponding replies.  They look like:
+
+@example
+user bar => NOTFOUND
+access connect:111.67.206.187 => OK REJECT
+@end example
+
+The part to the left of the @samp{=>} sign shows the query exactly as
+received from the client, i.e. the first word is the map name, and the
+rest of words constitute the key.  The part to the right of @samp{=>}
+is the reply to this query.
+
+  To enable query traces, use the @option{--trace} (@option{-T})
+command line option or @samp{trace yes} statement in the configuration
+file.
+
+  When using syslog, query traces are reported using the @samp{info}
+priority. 
+
+@anchor{trace-pattern}
+  Some requests may be of particular interest to you, whereas others
+may not be relevant at all.  There is a way to abridge the traces to
+show those relevant requests only.  If you give the
+@option{--trace-pattern=@var{pattern}} option, only those requests
+that begin with @var{pattern}@footnote{Actually, the argument would
+better be named @var{prefix}, but I plan to implement globbing
+patterns (or maybe even regular expressions) in future versions, so I
+refer to it as @var{pattern} in anticipation.} will be shown.  For
+example, to show only positive responses, use
+
+@example
+--trace --trace-pattern=OK
+@end example
+
+  The same can be requested in the configuration file as well:
+
+@example
+trace yes
+trace-pattern OK
+@end example
+
+  Any number of @option{--trace-pattern} options (or configuration
+statements) may be given.  The server will log only those queries that
+match one of the patterns specified by them.
+
+  @dfn{Debugging information} is auxiliary diagnostics reflecting
+various details of internal functionality of @command{smapd}.
+Although aimed primarily to help in debugging the server, it may
+occasionally be of use for server administrators as well.
+
+  Debugging information is requested using the @option{--debug}
+(@option{-x}) command line option or @samp{debug} configuration
+statement.  In both cases, the argument is a @dfn{debug
+specification}, consisting of two parts, separated by a dot:
+@samp{@var{cat}.@var{lev}}.  The @var{cat} part is a @dfn{debug
+category}.  It is either an integer number identifying the category,
+or its symbolic names.  For a list of categories and their meaning,
+see @ref{Debug Categories}.
+
+  The @var{lev} part is the category @dfn{level}, an integer specifying
+how much verbosity is requested from that category.  The @samp{0}
+value means no verbosity (i.e. to disable that category), the value of
+@samp{100} means maximum verbosity.  The convention is that levels
+below @samp{10} may be of occasional use for sysadmins, whereas higher
+values are useful only for debugging.
+
+  To enable several debug categories, use several @option{--debug}
+option (or @samp{debug} configuration statements).  
+
+@node options-smapd
+@section Command Line Syntax
+  Most command line options have two forms, called short and long
+forms. Both forms are absolutely identical in function; they are
+interchangeable. 
+
+  The @dfn{short} form is a traditional form for UNIX utilities.
+In this form, the option consists of a single dash, followed by a
+single letter, e.g. @option{-c}.
+
+  Short options which require arguments take their arguments
+immediately following the option letter, optionally separated by white
+space. For example, you might write @option{-f name}, or @option{-fname}.
+Here, @option{-f} is the option, and @option{name} is its argument.
+
+  Short options' letters may be clumped together, but you are not
+required to do this. When short options are clumped as a set, use one
+(single) dash for them all, e.g. @option{-cvl} is equivalent to @option{-c
+-v -l}. However, only options that do not take arguments may be
+clustered this way. If an option takes an argument, it can only be
+the last option in such a cluster, otherwise it would be impossible to
+specify the argument for it. Anyway, it is much more readable to
+specify such options separated.
+
+  The @dfn{long} option names are probably easier to memorize than
+their short counterparts. They consist of two dashes, followed by a
+multi-letter option name, which is usually selected to be a mnemonics
+for the operation it requests. For example, @option{--verbose} is a
+long option that increases the verbosity of a utility. In addition,
+long option names can abbreviated, provided that such an abbreviation
+is unique among the options understood by a given utility. For
+example, if a utility takes options @option{--foreground} and
+@option{--forward}, then the shortest possible abbreviations for these
+options are @option{--fore} and @option{--forw}, correspondingly. If
+you try to use @option{--for}, the utility will abort and inform you
+that the abbreviation you use is ambiguous, so it is not clear which
+of the options you intended to use.
+
+  Long options which require arguments take those arguments following
+the option name. There are two ways of specifying a mandatory
+argument. It can be separated from the option name either by an equal
+sign, or by any amount of white space characters. For example, if the
+@option{--file} option requires an argument, and you wish to supply
+@file{name} as its argument, then you can do so using any of the
+following notations: @option{--file=name} or @option{--file name}.
+
+  The following table summarizes the options available for
+@command{smapd}.  For each option a brief description is given
+and a cross reference is provided to more in-depth explanation in the
+body of the manual.
+
+@table @option
+@item -c @var{file}
+@itemx --config=@var{file}
+Read configuration from @var{file}, instead of the default
+@file{/etc/smapd.conf}.  @xref{smapd,, --config}.
+
+@item -t
+@itemx --lint
+Test configuration and exit with code @samp{0} if the file
+parsed without errors and @samp{78} otherwise.  Any errors found
+are reported on the standard error.  @xref{smapd,, --lint}.
+
+@item -f
+@itemx --foreground
+Do not detach from the controlling terminal, operate in foreground.
+
+@item -e
+@itemx --stderr
+Output diagnostic to stderr.  @xref{logging}.
+
+@item -l
+@itemx --syslog
+Output diagnostic to syslog (default).  @xref{logging}.
+
+@item -s
+@itemx --single-process
+Operate in single-process mode.  This option is intended to help in
+debugging @command{smapd}.  @emph{Do not use it in production
+environment!}
+
+@item -i
+@itemx --inetd
+Operate in inetd mode (@pxref{inetd-mode}).
+
+@item -T
+@itemx --trace
+Trace queries and replies.  @xref{debugging,, Query traces}.
+
+@item -p @var{pattern}
+@itemx --trace-pattern=@var{pattern}
+Trace only queries that begin with the given @var{pattern}.
+@xref{trace-pattern}.
+
+@item -x @var{level}
+@itemx --debug=@var{level}
+Set debug verbosity level.  @xref{debugging,,Debugging information}.
+
+@item -L
+@itemx --log-tag=@var{tag}
+Set syslog tag.  @xref{logging}.
+
+@item -f @var{facility}
+@itemx --log-facility=@var{facility}
+Set syslog facility.  @xref{logging,, log-facility}.
+
+@item  -h
+@itemx --help
+Give a concise summary of the command line options.
+
+@item --usage
+Give a short usage reminder.
+
+@item -V
+@itemx --version
+Print program version.
+@end table
+
+@node config-smapd
+@section Smapd Configuration File
+FIXME
+
+@node exit codes
+@section Smapd Exit Codes
+  The following table summarizes exit codes used by @command{smapd}.
+For each code it lists its decimal number, symbolic name from the
+@file{sysexits.h} header file, and its meaning.
+
+@multitable @columnfractions 0.1 0.2 0.7
+@headitem Code @tab Name @tab Meaning
+@item 0  @tab EX_OK @tab Normal termination.
+@item 64 @tab EX_USAGE @tab Command line usage error.
+@item 69 @tab EX_UNAVAILABLE @tab Some other error occurred.
+@item 78 @tab EX_CONFIG @tab Errors in configuration file detected.
+@end multitable
+
+@node  smapc
+@chapter Socket map client
+FIXME
 
 @node Reporting Bugs
 @chapter How to Report a Bug
@@ -169,6 +611,10 @@ under which it occurs, so we can reproduce it.
 @appendix The Sockmap Protocol
 @include sockmap.texi
 
+@node Debug Categories
+@appendix Debug Categories
+@include debugcat.texi
+
 @node Copying This Manual
 @appendix GNU Free Documentation License
 @include fdl.texi
diff --git a/doc/smapflow.eps b/doc/smapflow.eps
new file mode 100644
index 0000000..39087aa
--- /dev/null
+++ b/doc/smapflow.eps
@@ -0,0 +1,262 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: smapflow.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 4
+%%CreationDate: Wed Jun 16 08:02:41 2010
+%%For: gray@Trurl (Sergey Poznyakoff)
+%%BoundingBox: 0 0 382 326
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 326 moveto 0 0 lineto 382 0 lineto 382 326 lineto closepath clip newpath
+-49.0 340.0 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Polyline
+15.000 slw
+n 4919 1704 m 5940 1704 l 5940 2302 l 4919 2302 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+5165 2056 m
+gs 1 -1 sc (Mod A) col0 sh gr
+% Polyline
+n 4919 3182 m 5940 3182 l 5940 3781 l 4919 3781 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+5165 3534 m
+gs 1 -1 sc (Mod B) col0 sh gr
+% Polyline
+n 4919 4379 m 5940 4379 l 5940 4978 l 4919 4978 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+5165 4731 m
+gs 1 -1 sc (Mod C) col0 sh gr
+% Polyline
+n 2279 1457 m 3088 1457 l 3088 1985 l 2279 1985 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+2340 1755 m
+gs 1 -1 sc (Db "a") col0 sh gr
+% Polyline
+n 2279 2056 m 3088 2056 l 3088 2584 l 2279 2584 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+2340 2385 m
+gs 1 -1 sc (Db "b") col0 sh gr
+% Polyline
+n 2279 2654 m 3088 2654 l 3088 3182 l 2279 3182 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+2340 3015 m
+gs 1 -1 sc (Db "c") col0 sh gr
+% Polyline
+n 2279 3253 m 3088 3253 l 3088 3781 l 2279 3781 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+2340 3600 m
+gs 1 -1 sc (Db "d") col0 sh gr
+% Polyline
+n 2279 3851 m 3088 3851 l 3088 4379 l 2279 4379 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+2340 4185 m
+gs 1 -1 sc (Db "e") col0 sh gr
+% Polyline
+n 2279 4449 m 3088 4449 l 3088 4978 l 2279 4978 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+2340 4770 m
+gs 1 -1 sc (Db "f") col0 sh gr
+% Polyline
+n 1117 1809 m 1751 1809 l 1751 2302 l 1117 2302 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+1260 2115 m
+gs 1 -1 sc (RR) col0 sh gr
+% Polyline
+n 800 295 m 1927 295 l 1927 683 l 800 683 l
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+945 540 m
+gs 1 -1 sc (CLIENT) col0 sh gr
+% Polyline
+n 4924 260 m 4849 260 4849 643 75 arcto 4 {pop} repeat
+  4849 718 6006 718 75 arcto 4 {pop} repeat
+  6081 718 6081 335 75 arcto 4 {pop} repeat
+  6081 260 4924 260 75 arcto 4 {pop} repeat
+ cp gs col0 s gr 
+/Times-Bold ff 210.00 scf sf
+5085 540 m
+gs 1 -1 sc (libsmap) col0 sh gr
+% Polyline
+7.500 slw
+n 3088 4696 m
+ 4919 4696 l gs col0 s gr 
+% Polyline
+n 3088 3499 m
+ 4919 3499 l gs col0 s gr 
+% Polyline
+n 3088 2901 m 4919 3499 l
+ 3088 4133 l gs col0 s gr 
+% Polyline
+n 3088 1704 m 4039 1704 l
+ 4919 2020 l gs col0 s gr 
+% Polyline
+n 3088 2302 m 4039 2302 l
+ 4919 2020 l gs col0 s gr 
+% Polyline
+30.000 slw
+n 871 929 m 4039 929 l 4039 5365 l 871 5365 l
+ cp gs col0 s gr 
+% Polyline
+15.000 slw
+ [60] 0 sd
+gs  clippath
+1352 1824 m 1445 1824 l 1445 1588 l 1399 1776 l 1352 1588 l cp
+eoclip
+n 1399 683 m
+ 1399 1809 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 1352 1588 m 1399 1776 l 1445 1588 l  col0 s
+% Polyline
+ [90] 0 sd
+gs  clippath
+2270 2385 m 2314 2302 l 2106 2191 l 2250 2321 l 2062 2274 l cp
+eoclip
+n 1751 2056 m
+ 2279 2337 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 2062 2274 m 2250 2321 l 2106 2191 l  col0 s
+% Polyline
+ [90] 0 sd
+gs  clippath
+4913 2130 m 4883 2041 l 4660 2115 l 4853 2101 l 4689 2204 l cp
+eoclip
+n 3088 2372 m 4039 2372 l
+ 4884 2091 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 4689 2204 m 4853 2101 l 4660 2115 l  col0 s
+% Polyline
+7.500 slw
+n 5412 1704 m
+ 5412 718 l gs col0 s gr 
+% Polyline
+n 5940 3499 m 6538 3499 l 6538 471 l
+ 6081 471 l gs col0 s gr 
+% Polyline
+n 5940 4696 m 6820 4696 l 6820 436 l 6081 436 l
+ 6081 401 l gs col0 s gr 
+% Polyline
+30.000 slw
+ [97 49 15 49] 0 sd
+gs  clippath
+5528 703 m 5435 703 l 5435 938 l 5482 751 l 5528 938 l cp
+eoclip
+n 5482 1704 m
+ 5482 718 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+15.000 slw
+n 5528 938 m 5482 751 l 5435 938 l  col0 s
+% Polyline
+30.000 slw
+ [90 45 15 45] 0 sd
+gs  clippath
+1912 459 m 1912 554 l 2147 554 l 1960 507 l 2147 459 l cp
+eoclip
+n 4849 507 m
+ 1927 507 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+15.000 slw
+n 2147 459 m 1960 507 l 2147 554 l  col0 s
+/Times-Bold ff 210.00 scf sf
+1997 1176 m
+gs 1 -1 sc (S M A P D) col0 sh gr
+% here ends figure;
+$F2psEnd
+rs
+showpage
diff --git a/doc/smapflow.fig b/doc/smapflow.fig
new file mode 100644
index 0000000..81fe753
--- /dev/null
+++ b/doc/smapflow.fig
@@ -0,0 +1,103 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+6 4860 1665 5985 2340
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 4919 1704 5940 1704 5940 2302 4919 2302 4919 1704
+4 0 0 50 -1 2 14 0.0000 4 150 615 5165 2056 Mod A\001
+-6
+6 4860 3150 5985 3825
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 4919 3182 5940 3182 5940 3781 4919 3781 4919 3182
+4 0 0 50 -1 2 14 0.0000 4 150 615 5165 3534 Mod B\001
+-6
+6 4860 4320 5985 4995
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 4919 4379 5940 4379 5940 4978 4919 4978 4919 4379
+4 0 0 50 -1 2 14 0.0000 4 150 615 5165 4731 Mod C\001
+-6
+6 2250 1440 3105 2025
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2279 1457 3088 1457 3088 1985 2279 1985 2279 1457
+4 0 0 50 -1 2 14 0.0000 4 150 660 2340 1755 Db "a"\001
+-6
+6 2250 2025 3105 2610
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2279 2056 3088 2056 3088 2584 2279 2584 2279 2056
+4 0 0 50 -1 2 14 0.0000 4 150 675 2340 2385 Db "b"\001
+-6
+6 2250 2610 3105 3240
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2279 2654 3088 2654 3088 3182 2279 3182 2279 2654
+4 0 0 50 -1 2 14 0.0000 4 150 660 2340 3015 Db "c"\001
+-6
+6 2250 3195 3105 3825
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2279 3253 3088 3253 3088 3781 2279 3781 2279 3253
+4 0 0 50 -1 2 14 0.0000 4 150 660 2340 3600 Db "d"\001
+-6
+6 2250 3825 3105 4410
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2279 3851 3088 3851 3088 4379 2279 4379 2279 3851
+4 0 0 50 -1 2 14 0.0000 4 150 660 2340 4185 Db "e"\001
+-6
+6 2250 4410 3105 4995
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 2279 4449 3088 4449 3088 4978 2279 4978 2279 4449
+4 0 0 50 -1 2 14 0.0000 4 150 630 2340 4770 Db "f"\001
+-6
+6 1080 1755 1800 2340
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 1117 1809 1751 1809 1751 2302 1117 2302 1117 1809
+4 0 0 50 -1 2 14 0.0000 4 150 330 1260 2115 RR\001
+-6
+6 765 270 1980 720
+2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 800 295 1927 295 1927 683 800 683 800 295
+4 0 0 50 -1 2 14 0.0000 4 150 825 945 540 CLIENT\001
+-6
+6 4815 225 6120 765
+2 4 0 2 0 7 50 -1 -1 0.000 0 0 5 0 0 5
+	 6081 718 4849 718 4849 260 6081 260 6081 718
+4 0 0 50 -1 2 14 0.0000 4 195 750 5085 540 libsmap\001
+-6
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3088 4696 4919 4696
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3088 3499 4919 3499
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3088 2901 4919 3499 3088 4133
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3088 1704 4039 1704 4919 2020
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 3
+	 3088 2302 4039 2302 4919 2020
+2 2 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 871 929 4039 929 4039 5365 871 5365 871 929
+2 1 1 2 0 7 50 -1 -1 4.000 0 0 -1 1 0 2
+	0 0 2.00 93.88 187.75
+	 1399 683 1399 1809
+2 1 1 2 0 7 50 -1 -1 6.000 0 0 -1 1 0 2
+	0 0 2.00 93.88 187.75
+	 1751 2056 2279 2337
+2 1 1 2 0 7 50 -1 -1 6.000 0 0 -1 1 0 3
+	0 0 2.00 93.88 187.75
+	 3088 2372 4039 2372 4884 2091
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
+	 5412 1704 5412 718
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 4
+	 5940 3499 6538 3499 6538 471 6081 471
+2 1 0 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 5
+	 5940 4696 6820 4696 6820 436 6081 436 6081 401
+2 1 3 3 0 7 50 -1 -1 6.500 0 0 -1 1 0 2
+	0 0 2.00 93.88 187.75
+	 5482 1704 5482 718
+2 1 3 3 0 7 50 -1 -1 6.000 0 0 -1 1 0 2
+	0 0 2.00 94.50 187.50
+	 4849 507 1927 507
+4 0 0 50 -1 2 14 0.0000 4 150 1020 1997 1176 S M A P D\001
diff --git a/doc/smapflow.png b/doc/smapflow.png
new file mode 100644
index 0000000..148aa46
--- /dev/null
+++ b/doc/smapflow.png
diff --git a/doc/smapflow.txt b/doc/smapflow.txt
new file mode 100644
index 0000000..2ccdf45
--- /dev/null
+++ b/doc/smapflow.txt
@@ -0,0 +1,27 @@
+     +---------------+		       	      +---------------+	
+     |  C L I E N T  |<=::==:==:==:==:==:==:==| L I B S M A P |-+
+     +---------------+ 	       	       	      +---------------+ |
+             \/	       		    		      /\	|
+             ||	       	       	       	       	      ||	|
+             ||                                       ||        |
+         +---||----| S  M  A  P  D |---------+ 	      ..	|
+         |   ||                              |        ||        |
+         |   \/     +------+                 |        ||        |
+         |   ||     | db a |-----\           |     +-------+    |
+         | +----+   +------+      +======>=====>===| mod A |	|
+         | | RR |=>=| db b |==>=//           |     +-------+    |
+         | +----+   +------+                 |                  |
+         |          | db c |-----.           |                  |
+         |          +------+      \          |     +-------+    |
+         |          | db d |-------+---------------| mod B |----+
+         |          +------+      /          |     +-------+    |
+         |          | db e |-----'           |                  |
+         |          +------+                 |     +-------+    |
+         |          | db f |-----------------------| mod C |----+
+         |          +------+                 |     +-------+    
+         |                                   |                  
+         +-----------------------------------+
+
+
+
+