[Zodb-checkins] CVS: Packages/ZConfig/doc - zconfig.tex:1.37

[Fred L. Drake, Jr.]

Update of /cvs-repository/Packages/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv11713/doc

Modified Files:
	zconfig.tex 
Log Message:
Merge the zconfig-schema-devel-branch into the trunk for the ZConfig package.
Copyright notices get 2003 added as well.

The zconfig-schema-devel-branch should no longer be used.


=== Packages/ZConfig/doc/zconfig.tex 1.36 => 1.37 === (481/581 lines abridged)
--- Packages/ZConfig/doc/zconfig.tex:1.36	Thu Jan  2 13:31:53 2003
+++ Packages/ZConfig/doc/zconfig.tex	Fri Jan  3 16:05:54 2003
@@ -19,7 +19,16 @@
 \begin{abstract}
 \noindent
 This document describes the syntax and API used in configuration files
-for components of a Zope installation written by Zope Corporation.
+for components of a Zope installation written by Zope Corporation.  This
+configuration mechanism is itself configured using a schema specification
+written in XML.
+
+\begin{notice}[warning]
+  ZConfig have changed a great deal since this document was initially
+  written, and parts of this have not yet been updated, though
+  portions have been.  Please be patient as the documentation catches
+  up.
+\end{notice}
 \end{abstract}
 
 \tableofcontents
@@ -48,9 +57,9 @@
 format, this format supports key-value pairs arranged in sections.
 Unlike the \module{ConfigParser} format, sections are typed and can be
 organized hierarchically, and support delegation of value lookup to
-other sections.  Additional files may be imported or included at the
-top level if needed.  Though both formats are substantially
-line-oriented, this format is more flexible.
+other sections.  Additional files may be included if needed.  Though
+both formats are substantially line-oriented, this format is more
+flexible.
 
 The intent of supporting nested section is to allow setting up the
 configurations for loosely-associated components in a container.  For
@@ -59,7 +68,7 @@
 section may use the delegation syntax to share a base configuration
 with other components of the same type.
 
-The top level of a configuration file consists of a series of imports,
+The top level of a configuration file consists of a series of
 inclusions, key-value pairs, and sections.
 
 Comments can be added on lines by themselves.  A comment has a
@@ -70,21 +79,15 @@
 # This is a comment
 \end{verbatim}
 
-An import is expressed like this:
-
-\begin{verbatim}
-%import defaults.conf

[-=- -=- -=- 481 lines omitted -=- -=- -=-]

+The following method must be overridden by subclasses:
+
+\begin{methoddesc}[loader]{loadResource}{resource}
+  Subclasses of \class{BaseLoader} must implement this method to
+  actually load the resource and return the appropriate
+  application-level object.
+\end{methoddesc}
+
+The following methods can be used as utilities:
+
+\begin{methoddesc}[loader]{normalizeURL}{url-or-path}
+  Return a URL for \var{url-or-path}.  If \var{url-or-path} refers to
+  an existing file, the corresponding \code{file:} URL is returned.
+  Otherwise \var{url-or-path} is checked for sanity: if it
+  does not have a schema, \exception{ValueError} is raised, and if it
+  does have a fragment identifier, \exception{ConfigurationError} is
+  raised.
+\end{methoddesc}
+
+\begin{methoddesc}[loader]{openResource}{url}
+  Returns a resource object that represents the URL \var{url}.  The
+  URL is opened using the \function{urllib2.urlopen()} function, and
+  the returned resource object is created using
+  \method{createResource()}.
+\end{methoddesc}
+
+\begin{methoddesc}[loader]{createResource}{file, url}
+  Returns a resource object for an open file and URL, given as
+  \var{file} and \var{url}, respectively.  This may be overridden by a
+  subclass if an alternate resource implementation is desired.
 \end{methoddesc}
 
 
-\section{\module{ZConfig.Substitution} --- String substitution}
+\section{\module{ZConfig.substitution} --- String substitution}
 
-\declaremodule{}{ZConfig.Substitution}
+\declaremodule{}{ZConfig.substitution}
 \modulesynopsis{Shell-style string substitution helper.}
 
 This module provides a basic substitution facility similar to that
@@ -648,7 +962,7 @@
 \subsection{Examples}
 
 \begin{verbatim}
->>> from ZConfig.Substitution import substitute
+>>> from ZConfig.substitution import substitute
 >>> d = {'name': 'value',
 ...      'top': '$middle',
 ...      'middle' : 'bottom'}