[z3-checkins] r44552 - z3/deliverance/trunk
ianb at codespeak.net
ianb at codespeak.net
Tue Jun 26 21:55:53 CEST 2007
Author: ianb
Date: Tue Jun 26 21:55:51 2007
New Revision: 44552
Modified:
z3/deliverance/trunk/README.txt
z3/deliverance/trunk/setup.py
Log:
fiddling around with README.txt, added some stuff to setup.py for release
Modified: z3/deliverance/trunk/README.txt
==============================================================================
--- z3/deliverance/trunk/README.txt (original)
+++ z3/deliverance/trunk/README.txt Tue Jun 26 21:55:51 2007
@@ -32,37 +32,39 @@
Quick Start to build Deliverance
-----------------------------------
-The easiest way to get Deliverance installed is to checkout the
-buildout and follow the instructions found there.
+If you have recent versions of `lxml <http://codespeak.net/lxml/>`_
+installed, along with its underlying library `libxml2
+<http://xmlsoft.org/>`_, you should pretty much be okay. If you are
+getting segfaults or warnings, you might need newer software.
-$ svn co http://codespeak.net/svn/z3/deliverance/buildout/trunk
+If so, one way to get Deliverance installed is to checkout the
+buildout and follow the instructions found there::
+ $ svn co http://codespeak.net/svn/z3/deliverance/buildout/trunk
Otherwise, to install Deliverance manually, first get workingenv.py
from http://cheeseshop.python.org/pypi/workingenv.py. Create a working
-environment for Deliverance and its dependencies:
-
-$ workingenv.py deliverance_env
-$ source deliverance_env/bin/activate
+environment for Deliverance and its dependencies::
+ $ workingenv.py deliverance_env
+ $ source deliverance_env/bin/activate
Then install recent versions of libxml2, libxslt and lxml. You are
likely to encounter segfaults and other failures if recent versions
are not used.
Checkout and setup Deliverance, then make sure your installation is
-complete by running the tests:
-
-$ svn co http://codespeak.net/svn/z3/deliverance/trunk/ deliverance
-$ cd deliverance
-$ python setup.py develop
-$ nosetests
+complete by running the tests::
+ $ svn co http://codespeak.net/svn/z3/deliverance/trunk/ deliverance
+ $ cd deliverance
+ $ python setup.py develop
+ $ nosetests
-You can also run the tests like this:
+You can also run the tests like this::
-$ deliverance_env/bin/deliverance-tests
-$ deliverance_env/bin/deliverance-speed
+ $ deliverance_env/bin/deliverance-tests
+ $ deliverance_env/bin/deliverance-speed
----------------------------------------------
@@ -72,18 +74,19 @@
The deliverance proxy is a standalone application which serves a
themed version of some web location using a theme and a set of rules.
-eg:
-$ deliverance-proxy --serve=localhost:5001 --proxy=localhost:8080
- --theme=http://www.example.org
- --rule=file:///some/path/somerulesfile.xml
+::
+
+ $ deliverance-proxy --serve=localhost:5001 --proxy=localhost:8080
+ --theme=http://www.example.org
+ --rule=file:///some/path/somerulesfile.xml
This example provides a themed version of a local webserver at port
8080 served on port 5001. The theme page is http://www.example.org and
the rules are specified in somerulesfile.xml.
-For more options, run:
+For more options, run::
-$ deliverance-proxy --help
+ $ deliverance-proxy --help
------------------------------------------------
@@ -102,9 +105,9 @@
The command line tool used to execute Deliverance is called
-deliverance-handtransform. For instructions, run:
+deliverance-handtransform. For instructions, run::
-$ deliverance-handtransform --help
+ $ deliverance-handtransform --help
The theme, rules and other parameters are specified using command line
options -t, -r, etc. The result of the transform is output to
@@ -113,16 +116,16 @@
To avoid lengthy command lines, the tool can accept a "blend" file,
using the -f flag, which describes the theme and rules to apply.
-eg:
+eg::
-$ deliverance-handtransform -f ./blendfile.xml http://www.example.org
+ $ deliverance-handtransform -f ./blendfile.xml http://www.example.org
The second argument refers to the content; blendfile.xml contains
-something like:
+something like::
-<blend theme="http://www.example.org"
- baseurl="http://www.example.org"
- rules="./example-rules.xml" />
+ <blend theme="http://www.example.org"
+ baseurl="http://www.example.org"
+ rules="./example-rules.xml" />
@@ -130,31 +133,31 @@
Simple Tests
------------------------------------------------
-There are a number of tests in the test-data directory that follow the form:
+There are a number of tests in the test-data directory that follow the form::
-<?xml version="1.0" encoding="UTF-8"?>
-<deliverance-test-suite>
-<deliverance-test>
- <rules xmlns="http://www.plone.org/deliverance">
- ... rules as described at http://www.openplans.org/projects/deliverance/specification
- </rules>
-
- <theme base="http://example.com">
- ... theme html
- </theme>
-
- <content>
- ... content html
- </content>
+ <?xml version="1.0" encoding="UTF-8"?>
+ <deliverance-test-suite>
+ <deliverance-test>
+ <rules xmlns="http://www.plone.org/deliverance">
+ ... rules as described at http://www.openplans.org/projects/deliverance/specification
+ </rules>
+
+ <theme base="http://example.com">
+ ... theme html
+ </theme>
+
+ <content>
+ ... content html
+ </content>
- <output>
- ... expected output of applying rules to theme and content
- </output>
-</deliverance-test>
+ <output>
+ ... expected output of applying rules to theme and content
+ </output>
+ </deliverance-test>
-...
+ ...
-</deliverance-test-suite>
+ </deliverance-test-suite>
----------------------------------------------
WSGI Tests
@@ -173,78 +176,77 @@
This is an unstyled page produced by myBoringTodoList.com/deliverance_user/:
-this page is the content page:
-
-<html>
- <head>
- <title>my boring todo page</title>
- <head>
- <body>
- <div id="todo">
- <h1>Things To Do</h1>
- <ul>
- <li>Feed the cat</li>
- <li>Wash the dishes</li>
- </ul>
- </div>
- </body>
-</html>
+this page is the content page::
+ <html>
+ <head>
+ <title>my boring todo page</title>
+ <head>
+ <body>
+ <div id="todo">
+ <h1>Things To Do</h1>
+ <ul>
+ <li>Feed the cat</li>
+ <li>Wash the dishes</li>
+ </ul>
+ </div>
+ </body>
+ </html>
Here is another web page that typifies how we'd like to see the todo list
at excitingHomePage.com/deliverance_user/.
-this page is the theme:
+this page is the theme::
-<html>
- <head>
- <style type="text/css">
- div {background: #00ffdd;}
- li {list-style-type: disc;}
- </style>
- <title>my exciting home page</title>
- </head>
- <body>
- <h1>Deliverance User's Exciting Page</h1>
- <div id="wishes">
- I wish my todo list looked this cool
- </div>
- </body>
-</html>
+ <html>
+ <head>
+ <style type="text/css">
+ div {background: #00ffdd;}
+ li {list-style-type: disc;}
+ </style>
+ <title>my exciting home page</title>
+ </head>
+ <body>
+ <h1>Deliverance User's Exciting Page</h1>
+ <div id="wishes">
+ I wish my todo list looked this cool
+ </div>
+ </body>
+ </html>
Here are some deliverance rules that put the todo list into the
exciting home page and take away the wish. This tells deliverance
to replace the "wishes" div in the exciting home page with the
-"todo" div in the content page.
+"todo" div in the content page::
-<?xml version="1.0" encoding="UTF-8"?>
+ <?xml version="1.0" encoding="UTF-8"?>
-<rules xmlns="http://www.plone.org/deliverance" >
- <replace theme="//div[@id='wishes']" content="//div[@id='todo']" />
-</rules>
-
-Here is the output:
-
-<html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <style type="text/css">
- div {background: #00ffdd;}
- li {list-style-type: disc;}
- </style>
- <title>my exciting home page</title>
- </head>
- <body>
- <h1>Deliverance User's Exciting Page</h1>
- <div id="todo">
- <h1>Things To Do</h1>
- <ul>
- <li>Feed the cat</li>
- <li>Wash the dishes</li>
- <ul>
- </div>
- </body>
-</html>
+ <rules xmlns="http://www.plone.org/deliverance" >
+ <replace theme="//div[@id='wishes']" content="//div[@id='todo']" />
+ </rules>
+
+Here is the output::
+
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <style type="text/css">
+ div {background: #00ffdd;}
+ li {list-style-type: disc;}
+ </style>
+ <title>my exciting home page</title>
+ </head>
+ <body>
+ <h1>Deliverance User's Exciting Page</h1>
+ <div id="todo">
+ <h1>Things To Do</h1>
+ <ul>
+ <li>Feed the cat</li>
+ <li>Wash the dishes</li>
+ <ul>
+ </div>
+ </body>
+ </html>
see http://www.openplans.org/projects/deliverance for more information.
There are many other examples in deliverance/test-data
Modified: z3/deliverance/trunk/setup.py
==============================================================================
--- z3/deliverance/trunk/setup.py (original)
+++ z3/deliverance/trunk/setup.py Tue Jun 26 21:55:51 2007
@@ -4,16 +4,52 @@
setup(name="Deliverance",
version=__version__,
- description="",
+ description="Deliverance rewrites HTML to add theming",
long_description="""\
+Deliverance rewrites HTML pages to theme the pages -- adding things
+like navigation, stylesheets, and applying a common look-and-feel to
+content from a variety of sources.
+
+Unlike typical templating systems, Deliverance works only on HTML;
+there's no variables to substitute or Python structures involved. It
+takes a simple set of rules and applies these to the HTML, so you can
+style the output of pages regardless of where the page comes from.
+
+The theme itself is an HTML page with zero code in it. It is simply
+an example of what a page should look like; this makes it accessible
+to designers or any kind of tool, and may itself even be dynamically
+generated. For instance, you might use a blog page as a theme, and
+wrap that theme around a wiki to give the two a common look and feel.
+
+The rules are written in an XML format, that looks something like::
+
+ <rules xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns="http://www.plone.org/deliverance" >
+ <xi:include href="standardrules.xml" />
+ <copy theme="//div[@id='container']"
+ content="//*[@id='portal-columns']" />
+ </rules>
+
+This example, in addition to doing the 'standard' things (which
+includes merging the ``<head>`` of both pages) also copies the tag
+``<div id="portal-columns">`` into the theme page's
+``<div id="container">``.
+
+Deliverance is implemented as both a rendering object and WSGI
+middleware. Included in the package is a script that uses the WSGI
+middleware as an HTTP proxy.
""",
classifiers=[
- # dev status, license, HTTP categories
- ],
- keywords='',
- author="Paul Everitt",
- author_email="",
- url="",
+ 'Development Status :: 4 - Beta',
+ 'Intended Audience :: Developers',
+ 'Topic :: Internet :: WWW/HTTP',
+ 'Topic :: Internet :: WWW/HTTP :: WSGI',
+ 'Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware',
+ ],
+ keywords='templating html web wsgi middleware http proxy',
+ author="Deliverance Developer Community",
+ author_email="deliverance-devel at lists.openplans.org",
+ url="http://openplans.org/projects/deliverance",
license="",
packages=find_packages(exclude=[]),
zip_safe=False,
More information about the z3-checkins
mailing list