[Zodb-checkins] CVS: Packages/ZConfig/doc - zconfig.tex:1.51
Fred L. Drake, Jr.
fred@zope.com
Mon, 13 Jan 2003 15:16:33 -0500
Update of /cvs-repository/Packages/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv27060
Modified Files:
zconfig.tex
Log Message:
Preliminary documentation for a single element from the schema
language, trying to set the pattern for the reference portion of that
section.
=== Packages/ZConfig/doc/zconfig.tex 1.50 => 1.51 ===
--- Packages/ZConfig/doc/zconfig.tex:1.50 Mon Jan 13 12:51:31 2003
+++ Packages/ZConfig/doc/zconfig.tex Mon Jan 13 15:16:29 2003
@@ -1,4 +1,5 @@
\documentclass{howto}
+\usepackage{xmlmarkup}
\title{ZConfig Package Reference}
@@ -230,8 +231,7 @@
configuration values, and may contain references to named
definitions.
-For example, the value for the \code{key} will evaluate to
-\code{value}:
+For example, the value for \code{key} will evaluate to \code{value}:
\begin{verbatim}
%define name value
@@ -243,6 +243,61 @@
XXX to be written
+\module{ZConfig} schema are written as XML documents. The following
+elements are
+
+\begin{elementdesc}{key}{description?, example?, metadefault?}
+ A \element{key} element is used to describe a key-value pair which
+ may occur at most once in the section type or top-level schema in
+ which it is listed.
+
+ \begin{attributedesc}{attribute}{NMTOKEN}
+ The name of the Python attribute which this key should be the
+ value of on a \class{SectionValue} instance. This must be unique
+ within the immediate contents of a section type or schema. If
+ this attribute is not specified, an attribute name will be
+ computed by converting hyphens in the key name to underscores.
+ \end{attributedesc}
+
+ \begin{attributedesc}{datatype}{NMTOKEN}
+ The data type converter which will be applied to the value of this
+ key.
+ \end{attributedesc}
+
+ \begin{attributedesc}{default}{CDATA}
+ If the key-value pair is optional and this attribute is specified,
+ the value of this attribute will be converted using the appropiate
+ data type converter and returned to the application as the
+ configured value. This attribute may not be specified if the
+ \attribute{required} attribute is \code{yes}.
+ \end{attributedesc}
+
+ \begin{attributedesc}{handler}{NMTOKEN}
+ \end{attributedesc}
+
+ \begin{attributedesc}{name}{MNTOKEN}
+ The name of the key, as it must be given in a configuration
+ instance, or `\code{*}'. If the value is `\code{*}', any name not
+ already specified as a key may be used, and the configuration
+ value for the key will be a dictionary mapping from the key name
+ to the value. In this case, the \attribute{attribute} attribute
+ must be specified, and the data type for the key will be applied
+ to each key which is found.
+ \end{attributedesc}
+
+ \begin{attributedesc}{required}{yes|no}
+ Specifies whether the configuration instance is required to
+ provide the key. If the value is \code{yes}, the
+ \attribute{default} attribute may not be specified and an error
+ will be reported if the configuration instance does not specify a
+ value for the key. If the value is \code{no} (the default) and
+ the configuration instance does not specify a value, the value
+ reported the the application will be that specified by the
+ \attribute{default} attribute, if given, or \code{None}.
+ \end{attributedesc}
+\end{elementdesc}
+
+
\section{Schema Components \label{schema-components}}
@@ -270,18 +325,18 @@
A library of schema components is stored as a directory tree, where
each component is located in a directory within the tree. That
directory must contain a file named \file{component.xml} which defines
-the types provided by that component; it must have a \code{component}
-element as the document element. Extensions to a component are stored
-in immediate subdirectories; a file \file{extension.xml} provides the
-extension types. Extensions must have an \code{extension} element as
-the document element.
+the types provided by that component; it must have a
+\element{component} element as the document element. Extensions to a
+component are stored in immediate subdirectories; a file
+\file{extension.xml} provides the extension types. Extensions must
+have an \element{extension} element as the document element.
\section{Standard \module{ZConfig} Datatypes\label{standard-datatypes}}
There are a number of data types which can be identified using the
-\code{datatype} attribute on \code{key}, \code{multikey},
-\code{schema}, \code{section}, and \code{multisection} elements.
+\attribute{datatype} attribute on \element{key},
+\element{sectiontype}, and \element{schema} elements.
Applications may extend the set of datatypes by calling the
\method{register()} method of the data type regsitry being used or by
using Python dotted-names to refer to conversion routines defined in
@@ -310,7 +365,7 @@
\term{constructor}
Parse value in the form \samp{fn('1', '2', kw1='a', kw2='b')} into a
3-tuple where the first element is the string \code{'fn'}, the 2nd
- element is the list \code{['1','2']}, and the 3rd element is the
+ element is the list \code{['1', '2']}, and the 3rd element is the
dictionary \code{\{'kw1': 'a', 'kw2': 'b'\}}. This is useful when
representing a Python-style constructor as a value. Python syntax
rules are enforced, but only constants are allowed as positional and
@@ -683,7 +738,7 @@
constructor arguments. These objects also have a \method{close()}
method which will call \method{close()} on \var{file}, then set the
\member{file} attribute to \code{None} and the \member{closed} to
- \code{True}.
+ \constant{True}.
\end{classdesc}
\begin{classdesc}{BaseLoader}{}
@@ -811,8 +866,8 @@
\end{funcdesc}
\begin{funcdesc}{isname}{s}
- Returns \code{True} if \var{s} is a valid name for a substitution
- text, otherwise returns \code{False}.
+ Returns \constant{True} if \var{s} is a valid name for a substitution
+ text, otherwise returns \constant{False}.
\end{funcdesc}
@@ -831,6 +886,15 @@
\end{verbatim}
+\appendix
+\section{Schema Document Type Definition \label{schema-dtd}}
+
+The following is the XML Document Type Definition for \module{ZConfig}
+schema:
+
+\verbatiminput{schema.dtd}
+
+
% The modules described here have been left in the package while
% everything is updated to use the schema-based configurations.
@@ -1029,8 +1093,8 @@
\end{methoddesc}
\begin{methoddesc}[Configuration]{has_key}{key}
- Return \code{True} if \var{key} has an associated value, otherwise
- returns \code{False}.
+ Return \constant{True} if \var{key} has an associated value, otherwise
+ returns \constant{False}.
\end{methoddesc}
\begin{methoddesc}[Configuration]{items}{}