[Zope-Checkins] CVS: Zope/lib/python/ZConfig/doc - .cvsignore:1.2.4.1 Makefile:1.1.4.1 README.txt:1.1.4.1 zconfig.tex:1.5.4.1

[Chris McDonough]

Update of /cvs-repository/Zope/lib/python/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv2630/doc

Added Files:
      Tag: chrism-install-branch
	.cvsignore Makefile README.txt zconfig.tex 
Log Message:
Using "repolinked" ZConfig package rather than one checked directly in
to this branch.


=== Added File Zope/lib/python/ZConfig/doc/.cvsignore ===
zconfig.pdf
zconfig.ps


=== Added File Zope/lib/python/ZConfig/doc/Makefile ===
# Rules to convert the documentation to a single PDF file.

.PHONY:	default all pdf ps

default:  pdf
all:	  pdf ps

pdf:	zconfig.pdf
ps:	zconfig.ps

zconfig.pdf:  zconfig.tex
	mkhowto --pdf $<

zconfig.ps:  zconfig.tex
	mkhowto --postscript $<


=== Added File Zope/lib/python/ZConfig/doc/README.txt ===
The zconfig.tex document in this directory contains the reference
documentation for the ZConfig package.  This documentation is written
using the Python LaTeX styles.

To format the documentation, get a copy of the Python documentation
tools (the Doc/ directory from the Python sources), and create a
symlink to the tools/mkhowto script from some convenient bin/
directory.  You will need to have a fairly complete set of
documentation tools installed on your platform; see

    http://www.python.org/doc/current/doc/doc.html

for more information on the tools.


=== Added File Zope/lib/python/ZConfig/doc/zconfig.tex ===
\documentclass{howto}

\title{ZConfig Package Reference}

%\date{\today}
%\release{0.00}

\author{Zope Corporation}
\authoraddress{
    Lafayette Technology Center\\
    513 Prince Edward Street\\
    Fredericksburg, VA 22401\\
    \url{http://www.zope.com/}
}

\begin{document}
\maketitle

\begin{abstract}
\noindent
This document describes the syntax and API used in configuration files
for components of a Zope installation written by Zope Corporation.
\end{abstract}

\tableofcontents


\section{Introduction \label{intro}}

Zope uses a common syntax and API for configuration files designed for
software components written by Zope Corporation.  Third-party software
which is also part of a Zope installation may use a different syntax,
though any software is welcome to use the syntax used by Zope
Corporation.  Any software written in Python is free to use the
\module{ZConfig} software to load such configuration files in order to
ensure compatibility.  This software is covered by the Zope Public
License, version 2.0.

The \module{ZConfig} package has been tested with Python 2.1 and 2.2.
It only relies on the Python standard library.


\section{Configuration Syntax \label{syntax}}


\section{\module{ZConfig} --- Basic configuration support}

\declaremodule{}{ZConfig}
\modulesynopsis{Configuration package}


\section{\module{ZConfig.Context} --- Application context}

\declaremodule{}{ZConfig.Context}
\modulesynopsis{Application context}


\section{\module{ZConfig.Config} --- Section objects}

\declaremodule{}{ZConfig.Config}
\modulesynopsis{Standard section objects}


\section{\module{ZConfig.Common} --- Exceptions}

\declaremodule{}{ZConfig.Common}
\modulesynopsis{Exceptions}


\section{\module{ZConfig.ApacheStyle} --- Apache-style parser}

\declaremodule{}{ZConfig.ApacheStyle}
\modulesynopsis{Parser for Apache-style configurations}


\section{\module{ZConfig.Interpolation} --- String interpolation}

\declaremodule{}{ZConfig.Interpolation}
\modulesynopsis{Shell-style string interpolation helper}

This module provides a basic substitution facility similar to that
found in the Bourne shell (\program{sh} on most \UNIX{} platforms).  

The replacements supported by this module include:

\begin{tableiii}{l|l|c}{code}{Source}{Replacement}{Notes}
  \lineiii{\$\$}{\code{\$}}{(1)}
  \lineiii{\$\var{name}}{The result of looking up \var{name}}{(2)}
  \lineiii{\$\{\var{name}\}}{The result of looking up \var{name}}{}
\end{tableiii}

\noindent
Notes:
\begin{description}
  \item[(1)]  This is different from the Bourne shell, which uses
              \code{\textbackslash\$} to generate a \character{\$} in
              the result text.  This difference avoids having as many
              special characters in the syntax.

  \item[(2)]  Any character which immediately follows \var{name} may
              not be a valid character in a name.
\end{description}

In each case, \var{name} is a non-empty sequence of alphanumeric and
underscore characters not starting with a digit.  If there is not
a replacement for \var{name}, it is replaced with an empty string.

For these functions, the \var{mapping} argument can be a \class{dict},
or any type that supports the \method{get()} method of the mapping
protocol.

\begin{funcdesc}{interpolate}{s, mapping}
  Interpolate values from \var{mapping} into \var{s}.  Replacement
  values are copied into the result without further interpretation.
  Raises \exception{InterpolationSyntaxError} if there are malformed
  constructs in \var{s}.
\end{funcdesc}

\begin{funcdesc}{get}{mapping, name\optional{, default}}
  Return the value for \var{name} from \var{mapping}, interpolating
  values recursively if needed.  If \var{name} cannot be found in
  \var{mapping}, \var{default} is returned without being
  interpolated.
  Raises \exception{InterpolationSyntaxError} if there are malformed
  constructs in \var{s}, or \exception{InterpolationRecursionError} if
  any name expands to include a reference to itself either directly or
  indirectly.
\end{funcdesc}

The following exceptions are defined:

\begin{excdesc}{InterpolationError}
  Base class for errors raised by the \module{ZConfig.Interpolation}
  module.  Instances provide the attributes \member{message} and
  \member{context}.  \member{message} contains a description of the
  error.  \member{context} is either \code{None} or a list of names
  that have been looked up in the case of nested interpolation.
\end{excdesc}

\begin{excdesc}{InterpolationSyntaxError}
  Raised when interpolation source text contains syntactical errors.
\end{excdesc}

\begin{excdesc}{InterpolationRecursionError}
  Raised when a nested interpolation is recursive.  The
  \member{context} attribute will always be a list for this
  exception.  An additional attribute, \member{name}, gives the name
  for which an recursive reference was detected.
\end{excdesc}


\subsection{Examples}

These examples show how \function{get()} and \function{interpolate()}
differ.

\begin{verbatim}
>>> from ZConfig.Interpolation import get, interpolate
>>> d = {'name': 'value',
...      'top': '$middle',
...      'middle' : 'bottom'}
>>>
>>> interpolate('$name', d)
'value'
>>> interpolate('$top', d)
'$middle'
>>>
>>> get(d, 'name')
'value'
>>> get(d, 'top')
'bottom'
>>> get(d, 'missing', '$top')
'$top'
\end{verbatim}


\end{document}