[Zodb-checkins] CVS: Zope/lib/python/ZConfig/doc - zconfig.pdf:1.1.2.1 .cvsignore:1.2.58.2 Makefile:1.4.6.3 schema.dtd:1.3.2.1 xmlmarkup.perl:1.2.2.2 xmlmarkup.sty:1.2.2.2 zconfig.tex:1.47.2.2
Fred L. Drake, Jr.
fred@zope.com
Thu, 23 Jan 2003 17:02:31 -0500
Update of /cvs-repository/Zope/lib/python/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv32578/doc
Modified Files:
Tag: chrism-install-branch
.cvsignore Makefile schema.dtd xmlmarkup.perl xmlmarkup.sty
zconfig.tex
Added Files:
Tag: chrism-install-branch
zconfig.pdf
Log Message:
Merge from the ZConfig trunk.
=== Added File Zope/lib/python/ZConfig/doc/zconfig.pdf ===
<Binary-ish file>
=== Zope/lib/python/ZConfig/doc/.cvsignore 1.2.58.1 => 1.2.58.2 ===
--- Zope/lib/python/ZConfig/doc/.cvsignore:1.2.58.1 Mon Jan 13 20:17:30 2003
+++ Zope/lib/python/ZConfig/doc/.cvsignore Thu Jan 23 17:01:54 2003
@@ -1,3 +1,4 @@
zconfig
zconfig.pdf
zconfig.ps
+zconfig.txt
=== Zope/lib/python/ZConfig/doc/Makefile 1.4.6.2 => 1.4.6.3 ===
--- Zope/lib/python/ZConfig/doc/Makefile:1.4.6.2 Mon Jan 13 20:45:53 2003
+++ Zope/lib/python/ZConfig/doc/Makefile Thu Jan 23 17:01:54 2003
@@ -1,12 +1,26 @@
+##############################################################################
+#
+# Copyright (c) 2002, 2003 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+
# Rules to convert the documentation to a single PDF file.
#
-# PostScript and HTML output are also supported, though PDF is the
-# default.
+# PostScript, HTML, and plain text output are also supported, though
+# PDF is the default.
#
# See the README.txt file for information on the mkhowto program used
-# to generate the PDF and PostScript versions of the documentation.
+# to generate the formatted versions of the documentation.
-.PHONY: default all html pdf ps
+.PHONY: default all html pdf ps text
default: pdf
all: html pdf ps text
@@ -32,5 +46,5 @@
rm -f zconfig.l2h zconfig.l2h~
clobber: clean
- rm -f zconfig.pdf zconfig.ps
+ rm -f zconfig.pdf zconfig.ps zconfig.txt
rm -rf zconfig
=== Zope/lib/python/ZConfig/doc/schema.dtd 1.3 => 1.3.2.1 ===
--- Zope/lib/python/ZConfig/doc/schema.dtd:1.3 Thu Jan 9 21:56:21 2003
+++ Zope/lib/python/ZConfig/doc/schema.dtd Thu Jan 23 17:01:54 2003
@@ -1,3 +1,17 @@
+<!--
+ *************************************************************************
+ Copyright (c) 2002, 2003 Zope Corporation and Contributors.
+ All Rights Reserved.
+
+ This software is subject to the provisions of the Zope Public License,
+ Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+ THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+ WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+ FOR A PARTICULAR PURPOSE.
+ *************************************************************************
+ -->
+
<!-- DTD for ZConfig schema documents. -->
<!ELEMENT schema (description?, metadefault?, example?,
@@ -24,6 +38,9 @@
src CDATA #IMPLIED>
<!ELEMENT description (#PCDATA)*>
+<!ATTLIST description
+ format NMTOKEN #IMPLIED>
+
<!ELEMENT metadefault (#PCDATA)*>
<!ELEMENT example (#PCDATA)*>
=== Zope/lib/python/ZConfig/doc/xmlmarkup.perl 1.2.2.1 => 1.2.2.2 ===
--- Zope/lib/python/ZConfig/doc/xmlmarkup.perl:1.2.2.1 Mon Jan 13 20:17:30 2003
+++ Zope/lib/python/ZConfig/doc/xmlmarkup.perl Thu Jan 23 17:01:54 2003
@@ -1,15 +1,20 @@
+##############################################################################
+#
+# Copyright (c) 2003 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+
# LaTeX2HTML support for the xmlmarkup package. Doesn't do indexing.
package main;
-
-
-# sub ltx_next_argument{
-# my $param;
-# $param = missing_braces()
-# unless ((s/$next_pair_pr_rx/$param=$2;''/eo)
-# ||(s/$next_pair_rx/$param=$2;''/eo));
-# return $param;
-# }
sub do_cmd_element{
=== Zope/lib/python/ZConfig/doc/xmlmarkup.sty 1.2.2.1 => 1.2.2.2 ===
--- Zope/lib/python/ZConfig/doc/xmlmarkup.sty:1.2.2.1 Mon Jan 13 20:17:30 2003
+++ Zope/lib/python/ZConfig/doc/xmlmarkup.sty Thu Jan 23 17:01:54 2003
@@ -1,6 +1,17 @@
-% Created by Fred L. Drake, Jr. <fdrake@acm.org>, as part of the
-% Python Documentation Project.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
+% Copyright (c) 2003 Zope Corporation and Contributors.
+% All Rights Reserved.
+%
+% This software is subject to the provisions of the Zope Public License,
+% Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+% THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+% WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+% WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+% FOR A PARTICULAR PURPOSE.
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
% Define some simple markup for the LaTeX command documentation:
\ProvidesPackage{xmlmarkup}
=== Zope/lib/python/ZConfig/doc/zconfig.tex 1.47.2.1 => 1.47.2.2 ===
--- Zope/lib/python/ZConfig/doc/zconfig.tex:1.47.2.1 Mon Jan 13 20:17:30 2003
+++ Zope/lib/python/ZConfig/doc/zconfig.tex Thu Jan 23 17:01:54 2003
@@ -1,3 +1,17 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% Copyright (c) 2002, 2003 Zope Corporation and Contributors.
+% All Rights Reserved.
+%
+% This software is subject to the provisions of the Zope Public License,
+% Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+% THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+% WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+% WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+% FOR A PARTICULAR PURPOSE.
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\documentclass{howto}
\usepackage{xmlmarkup}
@@ -257,16 +271,52 @@
schema.
-\subsection{Schema Element Reference \label{schema-ref}}
+\subsection{Schema Elements \label{elements}}
XXX need to discuss notation
The following elements are used to describe a schema:
+\begin{elementdesc}{schema}{description?, metadefault?, example?,
+ import*,
+ (sectiontype | abstracttype)*,
+ (section | key | multisection |
+ multikey)*}
+ Document element for a \module{ZConfig} schema.
+
+ \begin{attributedesc}{datatype}{\datatype{basic-key}
+ or \datatype{dotted-name}}
+ The data type converter which will be applied to the value of this
+ section.
+ \end{attributedesc}
+
+ \begin{attributedesc}{handler}{\strong{basic-key}}
+ \end{attributedesc}
+
+ \begin{attributedesc}{keytype}{\strong{basic-key}}
+ \end{attributedesc}
+
+ \begin{attributedesc}{prefix}{\strong{dotted-name}}
+ \end{attributedesc}
+\end{elementdesc}
+
\begin{elementdesc}{description}{PCDATA}
Descriptive text explaining the purpose the container of the
\element{description} element. Most other elements can contain
a \element{description} element as their first child.
+
+ \begin{attributedesc}{format}{NMTOKEN}
+ Optional attribute that can be added to indicate what conventions
+ are used to mark up the contained text. This is intended to serve
+ as a hint for documentation extraction tools. Suggested values
+ are:
+
+ \begin{tableii}{l|l}{code}{Value}{Content Format}
+ \lineii{plain}{\mimetype{text/plain}; blank lines separate paragraphs}
+ \lineii{rest}{reStructuredText}
+ \lineii{stx}{Classic Structured Text}
+ \end{tableii}
+ \end{attributedesc}
\end{elementdesc}
\begin{elementdesc}{example}{PCDATA}
@@ -312,18 +362,34 @@
directly in a schema or other section type.
\end{attributedesc}
+ \begin{attributedesc}{keytype}{\strong{basic-key}}
+ \end{attributedesc}
+
\begin{attributedesc}{name}{\datatype{basic-key}}
The name of the section type; required.
\end{attributedesc}
+
+ \begin{attributedesc}{prefix}{\strong{dotted-name}}
+ \end{attributedesc}
\end{elementdesc}
\begin{elementdesc}{import}{EMPTY}
Import a schema component.
+ Exactly one of the two possible attributes must be specified.
\begin{attributedesc}{package}{\datatype{dotted-name}}
+ Python-package style name that identies a directory found on
+ \code{sys.path} containing a schema component in a file named
+ \file{component.xml}. Dots in the value are converted to
+ directory separators.
\end{attributedesc}
\begin{attributedesc}{src}{\datatype{url-reference}}
+ URL to a separate schema which can provide useful types. The
+ referenced resource must contain a schema, not a schema
+ component. Section types defined or imported by the referenced
+ schema are added to the schema containing the \element{import};
+ top-level keys and sections are ignored.
\end{attributedesc}
\end{elementdesc}
@@ -553,6 +619,26 @@
have an \element{extension} element as the document element.
+\subsection{Schema Component Elements \label{component-elements}}
+
+The following elements are used as the document elements of schema
+components and schema component extensions.
+
+\begin{elementdesc}{component}{description?, (abstracttype | sectiontype)*}
+ The top-level element for schema components.
+
+ \begin{attributedesc}{prefix}{\strong{dotted-name}}
+ \end{attributedesc}
+\end{elementdesc}
+
+\begin{elementdesc}{extensions}{description?, (abstracttype | sectiontype)*}
+ The top-level element for schema component extensions.
+
+ \begin{attributedesc}{prefix}{\strong{dotted-name}}
+ \end{attributedesc}
+\end{elementdesc}
+
+
\section{Standard \module{ZConfig} Datatypes\label{standard-datatypes}}
There are a number of data types which can be identified using the
@@ -581,7 +667,7 @@
\term{\datatype{byte-size}}
A specification of a size, with byte multiplier suffixes (for
example, \samp{128MB}). Suffixes are case insensitive and may be
- ``KB'', ``MB'', or ``GB''.
+ \samp{KB}, \samp{MB}, or \samp{GB}
\term{\datatype{constructor}}
Parse value in the form \samp{fn('1', '2', kw1='a', kw2='b')} into a
@@ -632,7 +718,8 @@
Validates a valid IP address or hostname. If the first
character is a digit, the value is assumed to be an IP
address. If the first character is not a digit, the value
- is assumed to be a hostname. No conversion is performed.
+ is assumed to be a hostname. Hostnames are converted to lower
+ case.
\term{\datatype{key-value}}
Parse a value in the form \code{'A B'} into the list \code{['A',
@@ -643,13 +730,6 @@
\function{locale.setlocale()} function. Be aware that only the
\code{'C'} locale is supported on some platforms.
-\term{\datatype{logging-level}}
- A logging level usable by the \module{logging} package. Valid
- values are the names \code{critical}, \code{fatal}, \code{error},
- \code{warn}, \code{info}, \code{debug}, and \code{all}, as well as
- integers in the range [0..50]. Converted values are always
- expressed as integers.
-
\term{\datatype{null}}
No conversion is performed; the value passed in is the value
returned. This is the default data type for section values.
@@ -678,9 +758,10 @@
configuration files.
\term{\datatype{time-interval}}
- A specification of a time interval, with multiplier suffixes,
- e.g. 12h. Suffixes are case insensitive and may be ``s'' (seconds),
- ``m'' (minutes), ``h'' (hours), or ``d'' (days).
+ A specification of a time interval, with multiplier suffixes (for
+ example, \code{12h}). Suffixes are case insensitive and may be
+ \samp{s} (seconds), \samp{m} (minutes), \samp{h} (hours), or
+ \samp{d} (days).
\end{definitions}
@@ -719,7 +800,10 @@
\end{funcdesc}
\begin{funcdesc}{loadSchema}{url}
- Load a schema definition from the URL \var{url}. The resulting
+ Load a schema definition from the URL \var{url}.
+ \var{url} may be a URL, absolute pathname, or relative pathname.
+ Fragment identifiers are not supported.
+ The resulting
schema object can be passed to \function{loadConfig()} or
\function{loadConfigFile()}. The schema object may be used as many
times as needed.