[Zope-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:27 -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.