Commit 9158fe56 authored by Fred Drake's avatar Fred Drake

- fix content model for <key>

- add discussion of the issues surrounding keys and multikeys with
  name="+" and default values
parent 2c816264
...@@ -511,7 +511,7 @@ The following elements are used to describe a schema: ...@@ -511,7 +511,7 @@ The following elements are used to describe a schema:
\end{attributedesc} \end{attributedesc}
\end{elementdesc} \end{elementdesc}
\begin{elementdesc}{key}{description?, example?, metadefault?} \begin{elementdesc}{key}{description?, example?, metadefault?, default*}
A \element{key} element is used to describe a key-value pair which 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 may occur at most once in the section type or top-level schema in
which it is listed. which it is listed.
...@@ -622,11 +622,52 @@ The following elements are used to describe a schema: ...@@ -622,11 +622,52 @@ The following elements are used to describe a schema:
element will be passed to the datatype conversion for the element will be passed to the datatype conversion for the
\element{multikey}. \element{multikey}.
\begin{attributedesc}{key}{} \begin{attributedesc}{key}{key type of the containing sectiontype}
Key to associate with the default value. This is only used for Key to associate with the default value. This is only used for
defaults of a \element{key} or \element{multikey} with a defaults of a \element{key} or \element{multikey} with a
\attribute{name} of \code{+}; in that case this attribute is \attribute{name} of \code{+}; in that case this attribute is
required. required. It is an error to use the \attribute{key} attribute
with a \element{default} element for a \element{multikey} with a
name other than \code{+}.
\begin{notice}[warning]
The datatype of this attribute is that of the section type
\emph{containing} the actual keys, not necessarily that of the
section type which defines the key. If a derived section
overrides the key type of the base section type, the actual
key type used is that of the derived section.
This can lead to confusing errors in schemas, though the
\refmodule{ZConfig} package checks for this when the schema is
loaded. This situation is particularly likely when a derived
section type uses a key type which collapses multiple default
keys which were not collapsed by the base section type.
Consider this example schema:
\begin{verbatim}
<schema>
<sectiontype name="base" keytype="identifier">
<key name="+" attribute="mapping">
<default key="foo">some value</default>
<default key="FOO">some value</default>
</key>
</sectiontype>
<sectiontype name="derived" keytype="basic-key"
extends="base"/>
<section type="derived" name="*" attribute="section"/>
</schema>
\end{verbatim}
When this schema is loaded, a set of defaults for the
\datatype{derived} section type is computed. Since
\datatype{basic-key} is case-insensitive (everything is
converted to lower case), \samp{foo} and \samp{Foo} are both
converted to \samp{foo}, which clashes since \element{key} only
allows one value for each key.
\end{notice}
\end{attributedesc} \end{attributedesc}
\end{elementdesc} \end{elementdesc}
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment