add a convenient mapping section type with documentation

doc/ZConfig/zconfig.tex

@@ -872,6 +872,113 @@ The following data types are provided by the default type registry.
 \end{definitions}
 
 
+\section{Standard \module{ZConfig} Schema Components
+         \label{standard-components}}
+
+\module{ZConfig} provides a few convenient schema components as part
+of the package.  These may be used directly or can server as examples
+for creating new components.
+
+
+\subsection{\module{ZConfig.components.basic}}
+
+The \module{ZConfig.components.basic} package provides small
+components that can be helpful in composing application-specific
+components and schema.  There is no large functionality represented by
+this package.  The default component provided by this package simply
+imports all of the smaller components.  This can be imported using
+
+\begin{verbatim}
+<import package="ZConfig.components.basic"/>
+\end{verbatim}
+
+Each of the smaller components is documented directly; importing these
+selectively can reduce the time it takes to load a schema slightly,
+and allows replacing the other basic components with alternate
+components (by using different imports that define the same type
+names) if desired.
+
+
+\subsubsection{The Mapping Section Type \label{basic-mapping}}
+
+There is a basic section type that behaves like a simple Python
+mapping; this can be imported directly using
+
+\begin{verbatim}
+<import package="ZConfig.components.basic" file="mapping.xml"/>
+\end{verbatim}
+
+This defines a single section type, \datatype{ZConfig.basic.mapping}.
+When this is used, the section value is a Python dictionary mapping
+keys to string values.
+
+This type is intended to be used by extending it in simple ways.  The
+simplest is to create a new section type name that makes more sense
+for the application:
+
+\begin{verbatim}
+<import package="ZConfig.components.basic" file="mapping.xml"/>
+
+<sectiontype name="my-mapping"
+             extends="ZConfig.basic.mapping"
+             />
+
+<section name="*"
+         type="my-mapping"
+         attribute="map"
+         />
+\end{verbatim}
+
+This allows a configuration to contain a mapping from
+\datatype{basic-key} names to string values like this:
+
+\begin{verbatim}
+<my-mapping>
+  This that
+  and the other
+</my-mapping>
+\end{verbatim}
+
+The value of the configuration object's \member{map} attribute would
+then be the dictionary
+
+\begin{verbatim}
+{'this': 'that',
+ 'and': 'the other',
+ }
+\end{verbatim}
+
+(Recall that the \datatype{basic-key} data type converts everything to
+lower case.)
+
+Perhaps a more interesting application of
+\datatype{ZConfig.basic.mapping} is using the derived type to override
+the \attribute{keytype}.  If we have the conversion function:
+
+\begin{verbatim}
+def email_address(value):
+    userid, hostname = value.split("@", 1)
+    hostname = hostname.lower()  # normalize what we know we can
+    return "%s@%s" % (userid, hostname)
+\end{verbatim}
+
+then we can use this as the key type for a derived mapping type:
+
+\begin{verbatim}
+<import package="ZConfig.components.basic" file="mapping.xml"/>
+
+<sectiontype name="email-users"
+             extends="ZConfig.basic.mapping"
+             keytype="mypkg.datatypes.email_address"
+             />
+
+<section name="*"
+         type="email-users"
+         attribute="email_users"
+         />
+\end{verbatim}
+
+
 \section{\module{ZConfig} --- Basic configuration support}
 
 \declaremodule{}{ZConfig}