========================================
DVNG Experimental Implementation
========================================

This directory contains the software, but not the documentation, for
an experimental implementation of Deliverance.

Usage
=====================

1) Generate a "compiledthemeset"::

  python ./dvngcompiler.py themeset1.xml > var/dvfinalstage.xsl

2) Apply it to some content and open the result::

  xsltproc var/dvfinalstage.xsl content3.html > var/output.html
  open var/output.html

3) Validate the "themeset" (aka rules file)::

  xmllint --relaxng themeset.rng themeset1.xml

Goals
=====================

- *Speed*. The current Deliverance renderers do a lot of work on each
  request. DVNG plans to do a lot of work once, with the result being
  usable not just between requests, but for as long as the theme and
  rules do not change.

- *Reliability*.  The production renderer is much less complex.

- *Debuggability*. By making each stage of the rendering introspectable
  in a "view source" fashion, you get some of the benefits of a
  pipeline. Namely, you know what part of the process broke down.

- *Extensibility*. Custom Deliverance rules, and even full-scale
  extensions via imported XSLT, provide ways to make specialized changes
  to the themes, rules, or even incoming content. All without adding
  more features to Deliverance.

Design
=====================

DVNG breaks the work of Deliverance up into two very fundamentally
different steps:

1) The integrator runs semi-complicated software to produced a
"compiled themeset".

2) For the most part, this "compiled themeset" is a standalone XSLT.
In production, it has very little custom software or implementation
complexity, beyond its use of XSLT as an intermediate language.

3) Extensibility is done either through normal XSL extensibility
features (by pointing at a custom XSL file for higher-precedence
template rules) or WSGI middleware.

Notes
=====================

- While any-old XSLT processor will work, to take advantage of
  grabbing stuff from non-content (e.g. the request) as match
  conditions, you need to gather up that information and pass it along
  as an XSL parameter.

- For deployment mode, such as installing Plone and using it with
  out-of-the-box themes, we could just point at xsltproc and fork a
  child process, to avoid lxml issues.

History
=====================


0.0.1 (June 3, 2008)
--------------------------

- Only the replace rule works

- Pagetypes are implemented and aggregate with themes

- Customization can be done via pointing at a custom xsl file for both
  cleaning up the theme before loading, as well as complex hacks on
  the content per-request.  See the breadcrumbs example in
  ``contentcustom.xsl``.

- An RNG that validates the "contract".  Also with embedded
  documentation, so people that use nxml-mode or oXygen can get help
  text as they do autocomplete.

- Not implemented:

  o Other rules

  o Any concept of link rewriting

  o Actually grabbing and passing in the extended match conditions
  such as req

  o No debugging, to flag when theme or content xpaths misfire

  o No support for CSS selectors yet

  o Switching the doctype requires some custom XSL mojo