Commits

Anonymous committed 7e2bc26

Some more distribution-related changes

  • Participants
  • Parent commits 3128d9e
  • Tags v0.1

Comments (0)

Files changed (8)

+=========================
+Django template utilities
+=========================
+
+This is a small library of template tags and other template-related
+utilities for use with Django; while Django does a great job in
+general of helping developers avoid repetitive code, there are still a
+few things which tend to be useful or even needed in many different
+types of projects, so this application aims to genericize and bundle
+many of them into one reusable package.
+
+
+Downloading and installing
+==========================
+
+
+The easiest download method is a Subversion_ checkout; all of the code
+is maintained in a Subversion repository, and checking the code out
+from the repository makes it easy to handle updates. To download and
+install, simply execute this command from a directory that's on your
+Python path::
+
+    svn co http://django-template-utils.googlecode.com/svn/trunk/template_utils/
+
+This will create a directory called ``template_utils``, and download
+the current code into it. From there, you should be able to add
+``template_utils`` to the ``INSTALLED_APPS`` setting of any Django
+project and have it work. This application provides no models, so you
+don't need to run ``manage.py syncdb`` before using it.
+
+.. _Subversion: http://subversion.tigris.org/
+
+
+Using ``distutils``
+-------------------
+
+Alternatively, you can download a packaged version of the entire
+application and use Python's ``distutils`` to install it::
+
+    wget http://django-template-utils.googlecode.com/files/template_utils-0.1.tar.gz
+    tar zxvf template_utils-0.1.tar.gz
+    cd template_utils-0.1
+    python setup.py install
+
+
+
+Feature overview
+================
+
+Currently, five main components are bundled into ``template_utils``:
+
+    * Template tags for `generic content retrieval`_.
+
+    * Template tags for `robust comparison operations`_.
+
+    * Template tags for `retrieving public comments`_ (for when a
+      comment-moderation system is in use).
+
+    * A `generic text-to-HTML conversion system`_ with template filter
+      support.
+
+    * A system for generating `template context processors`_ which can
+      add arbitrary settings to template contexts.
+
+.. _generic content retrieval: docs/generic_content.html
+.. _robust comparison operations: docs/comparison.html
+.. _retrieving public comments: docs/public_comments.html
+.. _generic text-to-HTML conversion system: docs/markup.html
+.. _template context processors: docs/context_processors.html

File docs/comparison.html

-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
-<title>Comparison tags</title>
-<style type="text/css">
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
-:Revision: $Revision: 4224 $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
-  border: 0 }
-
-table.borderless td, table.borderless th {
-  /* Override padding for "table.docutils td" with "! important".
-     The right padding separates the table cells. */
-  padding: 0 0.5em 0 0 ! important }
-
-.first {
-  /* Override more specific margin styles with "! important". */
-  margin-top: 0 ! important }
-
-.last, .with-subtitle {
-  margin-bottom: 0 ! important }
-
-.hidden {
-  display: none }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-blockquote.epigraph {
-  margin: 2em 5em ; }
-
-dl.docutils dd {
-  margin-bottom: 0.5em }
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
-  font-weight: bold }
-*/
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
-   compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
-  margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
-  margin-top: 0.5em }
-*/
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em ;
-  margin-right: 2em }
-
-div.footer, div.header {
-  clear: both;
-  font-size: smaller }
-
-div.line-block {
-  display: block ;
-  margin-top: 1em ;
-  margin-bottom: 1em }
-
-div.line-block div.line-block {
-  margin-top: 0 ;
-  margin-bottom: 0 ;
-  margin-left: 1.5em }
-
-div.sidebar {
-  margin-left: 1em ;
-  border: medium outset ;
-  padding: 1em ;
-  background-color: #ffffee ;
-  width: 40% ;
-  float: right ;
-  clear: right }
-
-div.sidebar p.rubric {
-  font-family: sans-serif ;
-  font-size: medium }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
-  margin-top: 0.4em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr.docutils {
-  width: 75% }
-
-img.align-left {
-  clear: left }
-
-img.align-right {
-  clear: right }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.attribution {
-  text-align: right ;
-  margin-left: 50% }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.rubric {
-  font-weight: bold ;
-  font-size: larger ;
-  color: maroon ;
-  text-align: center }
-
-p.sidebar-title {
-  font-family: sans-serif ;
-  font-weight: bold ;
-  font-size: larger }
-
-p.sidebar-subtitle {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option {
-  white-space: nowrap }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-span.section-subtitle {
-  /* font-size relative to parent (h1..h6 element) */
-  font-size: 80% }
-
-table.citation {
-  border-left: solid 1px gray;
-  margin-left: 1px }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.docutils {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.footnote {
-  border-left: solid 1px black;
-  margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap ;
-  padding-left: 0 }
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
-  font-size: 100% }
-
-tt.docutils {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="comparison-tags">
-<h1 class="title">Comparison tags</h1>
-<p>It's usually a bad idea to have a lot of logic in your templates, but
-occasionally there's a true presentational need for certain
-operations. Django provides an <cite>ifequal</cite> tag which tests equality of
-two values, and this tag library supplements it by providing a set of
-tags which can handle other types of comparisons.</p>
-<p>To use these tags, you'll need to have <tt class="docutils literal"><span class="pre">template_utils</span></tt> in your
-<tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt> list, and you'll need to have <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">comparison</span>
-<span class="pre">%}</span></tt> in your template.</p>
-<div class="section">
-<h1><a id="if-greater" name="if-greater"><tt class="docutils literal"><span class="pre">if_greater</span></tt></a></h1>
-<p>Tests whether one value is greater than another.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% if_greater [var1] [var2] %}
-...do something...
-{% else %}
-...do something else...
-{% endif_greater %}
-</pre>
-<p>The <tt class="docutils literal"><span class="pre">else</span></tt> clause is optional, and <tt class="docutils literal"><span class="pre">var1</span></tt> and <tt class="docutils literal"><span class="pre">var2</span></tt> can be
-template variables or literal values.</p>
-<p>Example:</p>
-<pre class="literal-block">
-{% if_greater forloop.counter 1 %}
-&lt;p&gt;We've been through the loop at least twice.&lt;/p&gt;
-{% else %}
-&lt;p&gt;This is one of the first two times through the loop.&lt;/p&gt;
-{% endif_greater %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="if-greater-or-equal" name="if-greater-or-equal"><tt class="docutils literal"><span class="pre">if_greater_or_equal</span></tt></a></h1>
-<p>Similar to the <tt class="docutils literal"><span class="pre">if_greater</span></tt> tag, but applies a &quot;greater than or
-equal to&quot; comparison.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% if_greater_or_equal [var1] [var2] %}
-...do something...
-{% else %}
-...do something else...
-{% endif_greater_or_equal %}
-</pre>
-<p>The <tt class="docutils literal"><span class="pre">else</span></tt> clause is optional, and <tt class="docutils literal"><span class="pre">var1</span></tt> and <tt class="docutils literal"><span class="pre">var2</span></tt> can be
-template variables or literal values.</p>
-</div>
-<div class="section">
-<h1><a id="if-less" name="if-less"><tt class="docutils literal"><span class="pre">if_less</span></tt></a></h1>
-<p>Similar to the <tt class="docutils literal"><span class="pre">if_greater</span></tt> tag, but tests whether one value is less
-than another.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% if_less [var1] [var2] %}
-...do something...
-{% else %}
-...do something else...
-{% endif_less %}
-</pre>
-<p>The <tt class="docutils literal"><span class="pre">else</span></tt> clause is optional, and <tt class="docutils literal"><span class="pre">var1</span></tt> and <tt class="docutils literal"><span class="pre">var2</span></tt> can be
-template variables or literal values.</p>
-</div>
-<div class="section">
-<h1><a id="if-less-or-equal" name="if-less-or-equal"><tt class="docutils literal"><span class="pre">if_less_or_equal</span></tt></a></h1>
-<p>Similar to the <tt class="docutils literal"><span class="pre">if_less</span></tt> tag, but applies a &quot;lessthan or equal to&quot;
-comparison.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% if_less_or_equal [var1] [var2] %}
-...do something...
-{% else %}
-...do something else...
-{% endif_less_or_equal %}
-</pre>
-<p>The <tt class="docutils literal"><span class="pre">else</span></tt> clause is optional, and <tt class="docutils literal"><span class="pre">var1</span></tt> and <tt class="docutils literal"><span class="pre">var2</span></tt> can be
-template variables or literal values.</p>
-</div>
-</div>
-</body>
-</html>

File docs/context_processors.html

-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
-<title>Context processors for settings</title>
-<style type="text/css">
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
-:Revision: $Revision: 4224 $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
-  border: 0 }
-
-table.borderless td, table.borderless th {
-  /* Override padding for "table.docutils td" with "! important".
-     The right padding separates the table cells. */
-  padding: 0 0.5em 0 0 ! important }
-
-.first {
-  /* Override more specific margin styles with "! important". */
-  margin-top: 0 ! important }
-
-.last, .with-subtitle {
-  margin-bottom: 0 ! important }
-
-.hidden {
-  display: none }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-blockquote.epigraph {
-  margin: 2em 5em ; }
-
-dl.docutils dd {
-  margin-bottom: 0.5em }
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
-  font-weight: bold }
-*/
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
-   compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
-  margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
-  margin-top: 0.5em }
-*/
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em ;
-  margin-right: 2em }
-
-div.footer, div.header {
-  clear: both;
-  font-size: smaller }
-
-div.line-block {
-  display: block ;
-  margin-top: 1em ;
-  margin-bottom: 1em }
-
-div.line-block div.line-block {
-  margin-top: 0 ;
-  margin-bottom: 0 ;
-  margin-left: 1.5em }
-
-div.sidebar {
-  margin-left: 1em ;
-  border: medium outset ;
-  padding: 1em ;
-  background-color: #ffffee ;
-  width: 40% ;
-  float: right ;
-  clear: right }
-
-div.sidebar p.rubric {
-  font-family: sans-serif ;
-  font-size: medium }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
-  margin-top: 0.4em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr.docutils {
-  width: 75% }
-
-img.align-left {
-  clear: left }
-
-img.align-right {
-  clear: right }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.attribution {
-  text-align: right ;
-  margin-left: 50% }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.rubric {
-  font-weight: bold ;
-  font-size: larger ;
-  color: maroon ;
-  text-align: center }
-
-p.sidebar-title {
-  font-family: sans-serif ;
-  font-weight: bold ;
-  font-size: larger }
-
-p.sidebar-subtitle {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option {
-  white-space: nowrap }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-span.section-subtitle {
-  /* font-size relative to parent (h1..h6 element) */
-  font-size: 80% }
-
-table.citation {
-  border-left: solid 1px gray;
-  margin-left: 1px }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.docutils {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.footnote {
-  border-left: solid 1px black;
-  margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap ;
-  padding-left: 0 }
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
-  font-size: 100% }
-
-tt.docutils {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="context-processors-for-settings">
-<h1 class="title">Context processors for settings</h1>
-<p>It's often useful for an application to expose the values of certain
-settings -- especially custom settings -- for use in
-templates. Django's <tt class="docutils literal"><span class="pre">RequestContext</span></tt> and context processors provide
-an easy way to automatically add certain variables to every template
-context, but (for good reasons) Django does not provide a context
-processor which can expose the values of settings.</p>
-<p>This module provides a simple function which can generate context
-processors for settings, and a pre-generated context processor for the
-most common use case: media settings.</p>
-<div class="section">
-<h1><a id="template-utils-context-processors-settings-processor" name="template-utils-context-processors-settings-processor"><tt class="docutils literal"><span class="pre">template_utils.context_processors.settings_processor</span></tt></a></h1>
-<p>This function takes a list of setting names, and returns a new
-function: a context processor which will add the values of those
-settings to any <tt class="docutils literal"><span class="pre">RequestContext</span></tt> in which it is used.</p>
-<p>So, for example, you might define a file <tt class="docutils literal"><span class="pre">context_processors.py</span></tt> in
-your application, and place the following in it:</p>
-<pre class="literal-block">
-from template_utils.context_processors import settings_processor
-my_settings_processor = settings_processor('INTERNAL_IPS', 'SITE_ID')
-</pre>
-<p>The function <tt class="docutils literal"><span class="pre">my_settings_processor</span></tt> would be a context processor
-which added the values of the settings <tt class="docutils literal"><span class="pre">INTERNAL_IPS</span></tt> and
-<tt class="docutils literal"><span class="pre">SITE_ID</span></tt> to each <tt class="docutils literal"><span class="pre">RequestContext</span></tt> in which it was used, and then
-you would just need to add
-<tt class="docutils literal"><span class="pre">myproject.myapp.context_processors.my_settings_processor</span></tt> (changing
-the name to suit the actual names of your project and application, of
-course) to your `` TEMPLATE_CONTEXT_PROCESSORS`` setting.</p>
-</div>
-<div class="section">
-<h1><a id="template-utils-context-processors-media" name="template-utils-context-processors-media"><tt class="docutils literal"><span class="pre">template_utils.context_processors.media</span></tt></a></h1>
-<p>This is a pre-generated context processor which adds the values of the
-settings <tt class="docutils literal"><span class="pre">MEDIA_URL</span></tt> and <tt class="docutils literal"><span class="pre">ADMIN_MEDIA_PREFIX</span></tt> to each
-<tt class="docutils literal"><span class="pre">RequestContext</span></tt> in which it is used.</p>
-<p>To enable it, add <tt class="docutils literal"><span class="pre">template_utils.context_processors.media</span></tt> to your
-<tt class="docutils literal"><span class="pre">TEMPLATE_CONTEXT_PROCESSORS</span></tt> setting.</p>
-</div>
-</div>
-</body>
-</html>

File docs/generic_content.html

-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
-<title>Generic content retrieval</title>
-<style type="text/css">
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
-:Revision: $Revision: 4224 $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
-  border: 0 }
-
-table.borderless td, table.borderless th {
-  /* Override padding for "table.docutils td" with "! important".
-     The right padding separates the table cells. */
-  padding: 0 0.5em 0 0 ! important }
-
-.first {
-  /* Override more specific margin styles with "! important". */
-  margin-top: 0 ! important }
-
-.last, .with-subtitle {
-  margin-bottom: 0 ! important }
-
-.hidden {
-  display: none }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-blockquote.epigraph {
-  margin: 2em 5em ; }
-
-dl.docutils dd {
-  margin-bottom: 0.5em }
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
-  font-weight: bold }
-*/
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
-   compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
-  margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
-  margin-top: 0.5em }
-*/
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em ;
-  margin-right: 2em }
-
-div.footer, div.header {
-  clear: both;
-  font-size: smaller }
-
-div.line-block {
-  display: block ;
-  margin-top: 1em ;
-  margin-bottom: 1em }
-
-div.line-block div.line-block {
-  margin-top: 0 ;
-  margin-bottom: 0 ;
-  margin-left: 1.5em }
-
-div.sidebar {
-  margin-left: 1em ;
-  border: medium outset ;
-  padding: 1em ;
-  background-color: #ffffee ;
-  width: 40% ;
-  float: right ;
-  clear: right }
-
-div.sidebar p.rubric {
-  font-family: sans-serif ;
-  font-size: medium }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
-  margin-top: 0.4em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr.docutils {
-  width: 75% }
-
-img.align-left {
-  clear: left }
-
-img.align-right {
-  clear: right }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.attribution {
-  text-align: right ;
-  margin-left: 50% }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.rubric {
-  font-weight: bold ;
-  font-size: larger ;
-  color: maroon ;
-  text-align: center }
-
-p.sidebar-title {
-  font-family: sans-serif ;
-  font-weight: bold ;
-  font-size: larger }
-
-p.sidebar-subtitle {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option {
-  white-space: nowrap }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-span.section-subtitle {
-  /* font-size relative to parent (h1..h6 element) */
-  font-size: 80% }
-
-table.citation {
-  border-left: solid 1px gray;
-  margin-left: 1px }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.docutils {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.footnote {
-  border-left: solid 1px black;
-  margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap ;
-  padding-left: 0 }
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
-  font-size: 100% }
-
-tt.docutils {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="generic-content-retrieval">
-<h1 class="title">Generic content retrieval</h1>
-<p>A common task in Django applications is writing template tags which
-retrieve particular pieces of content; for example, a weblog might
-need a &quot;get latest entries&quot; tag, while a news site would want &quot;get
-latest stories&quot;, and so on. Writing these tags to work only with
-specific models results in duplication of code across applications, so
-<tt class="docutils literal"><span class="pre">template_utils</span></tt> provides a set of template tags which can retrieve
-content from any installed model, according to certain criteria.</p>
-<p>To use these tags, you'll need to have <tt class="docutils literal"><span class="pre">template_utils</span></tt> in your
-<tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt> list, and you'll need to have <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span>
-<span class="pre">generic_content</span> <span class="pre">%}</span></tt> in your template.</p>
-<div class="section">
-<h1><a id="get-latest-object" name="get-latest-object"><tt class="docutils literal"><span class="pre">get_latest_object</span></tt></a></h1>
-<p>This tag retrieves the &quot;latest&quot; object from a model, according to the
-model's default ordering.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_latest_object [app_name].[model_name] as [varname] %}
-</pre>
-<p>So, for example, to retrieve the latest <tt class="docutils literal"><span class="pre">FreeComment</span></tt> posted:</p>
-<pre class="literal-block">
-{% get_latest_object comments.freecomment as latest_comment %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="get-latest-objects" name="get-latest-objects"><tt class="docutils literal"><span class="pre">get_latest_objects</span></tt></a></h1>
-<p>Similar to <tt class="docutils literal"><span class="pre">get_latest_object</span></tt>, but takes an additional argument --
-a number -- and returns a list of that many objects.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_latest_objects [app_name].[model_name] [num] as [varname] %}
-</pre>
-<p>Continuing with comments as an example:</p>
-<pre class="literal-block">
-{% get_latest_objects comments.freecomment 5 as latest_comments %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="get-random-object" name="get-random-object"><tt class="docutils literal"><span class="pre">get_random_object</span></tt></a></h1>
-<p>Retrieves a single object, randomly selected, from a model.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_random_object [app_name].[model_name] as [varname] %}
-</pre>
-<p>So to retrieve a random comment:</p>
-<pre class="literal-block">
-{$ get_random_object comments.freecomment as random_comment %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="get-random-objects" name="get-random-objects"><tt class="docutils literal"><span class="pre">get_random_objects</span></tt></a></h1>
-<p>Much like <tt class="docutils literal"><span class="pre">get_latest_objects</span></tt>, this tag returns a given number of
-objects (randomly selected).</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_random_object [app_name].[model_name] as [varname] %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="retrieve-object" name="retrieve-object"><tt class="docutils literal"><span class="pre">retrieve_object</span></tt></a></h1>
-<p>Retrieves a single specific object by primary-key lookup.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% retrieve_object [app_name].[model_name] [primary_key] as [varname] %}
-</pre>
-<p>For example, if you wanted to retrieve a flatpage with <tt class="docutils literal"><span class="pre">id</span></tt> 12:</p>
-<pre class="literal-block">
-{% retrieve_object flatpages.flatpage 12 as my_flatpage %}
-</pre>
-</div>
-</div>
-</body>
-</html>

File docs/markup.html

-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
-<title>Generic text-to-HTML conversion</title>
-<style type="text/css">
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
-:Revision: $Revision: 4224 $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
-  border: 0 }
-
-table.borderless td, table.borderless th {
-  /* Override padding for "table.docutils td" with "! important".
-     The right padding separates the table cells. */
-  padding: 0 0.5em 0 0 ! important }
-
-.first {
-  /* Override more specific margin styles with "! important". */
-  margin-top: 0 ! important }
-
-.last, .with-subtitle {
-  margin-bottom: 0 ! important }
-
-.hidden {
-  display: none }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-blockquote.epigraph {
-  margin: 2em 5em ; }
-
-dl.docutils dd {
-  margin-bottom: 0.5em }
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
-  font-weight: bold }
-*/
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
-   compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
-  margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
-  margin-top: 0.5em }
-*/
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em ;
-  margin-right: 2em }
-
-div.footer, div.header {
-  clear: both;
-  font-size: smaller }
-
-div.line-block {
-  display: block ;
-  margin-top: 1em ;
-  margin-bottom: 1em }
-
-div.line-block div.line-block {
-  margin-top: 0 ;
-  margin-bottom: 0 ;
-  margin-left: 1.5em }
-
-div.sidebar {
-  margin-left: 1em ;
-  border: medium outset ;
-  padding: 1em ;
-  background-color: #ffffee ;
-  width: 40% ;
-  float: right ;
-  clear: right }
-
-div.sidebar p.rubric {
-  font-family: sans-serif ;
-  font-size: medium }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
-  margin-top: 0.4em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr.docutils {
-  width: 75% }
-
-img.align-left {
-  clear: left }
-
-img.align-right {
-  clear: right }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.attribution {
-  text-align: right ;
-  margin-left: 50% }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.rubric {
-  font-weight: bold ;
-  font-size: larger ;
-  color: maroon ;
-  text-align: center }
-
-p.sidebar-title {
-  font-family: sans-serif ;
-  font-weight: bold ;
-  font-size: larger }
-
-p.sidebar-subtitle {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option {
-  white-space: nowrap }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-span.section-subtitle {
-  /* font-size relative to parent (h1..h6 element) */
-  font-size: 80% }
-
-table.citation {
-  border-left: solid 1px gray;
-  margin-left: 1px }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.docutils {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.footnote {
-  border-left: solid 1px black;
-  margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap ;
-  padding-left: 0 }
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
-  font-size: 100% }
-
-tt.docutils {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="generic-text-to-html-conversion">
-<h1 class="title">Generic text-to-HTML conversion</h1>
-<p>It's extremely common to use some form of text-to-HTML conversion
-utility, such as Markdown or Textile, to allow plain text entered by
-staff members or users to be transformed into HTML for output, and not
-terribly uncommon to even store that generated HTML in the database,
-by having it converted when a model instance is saved. And, in the
-bundled <tt class="docutils literal"><span class="pre">django.contrib.markup</span></tt>, Django provides template filters
-which can be used for Markdown, Textile and reStructuredText, making
-this even easier to do.</p>
-<p>The downside to all of this is that your code becomes coupled to the
-particular system you're using: if you use Markdown, for example, you
-end up applying the <tt class="docutils literal"><span class="pre">markdown</span></tt> filter in all of your templates, or
-hard-coding a call to <tt class="docutils literal"><span class="pre">markdown.markdown</span></tt> in a model's <tt class="docutils literal"><span class="pre">save</span></tt>
-method. And although most of the popular text-to-HTML converters
-support lots of useful options, Django's template filters don't really
-offer a way to take advantage of them.</p>
-<p>This module provides a generic <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt> class which aims to
-solve these problems; it is designed to allow the use of any
-text-to-HTML converter with minimal coupling of your code.</p>
-<div class="section">
-<h1><a id="overview" name="overview">Overview</a></h1>
-<p>The <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt> class handles text-to-HTML conversion by using
-&quot;filter functions&quot;; by default, three filters are available:
-<tt class="docutils literal"><span class="pre">markdown</span></tt>, <tt class="docutils literal"><span class="pre">textile</span></tt> and <tt class="docutils literal"><span class="pre">restructuredtext</span></tt>, which apply those
-systems. You can, however, enable the use of any system you like by
-writing a new filter function and registering it with an instance of
-<tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt>.</p>
-</div>
-<div class="section">
-<h1><a id="basic-usage" name="basic-usage">Basic usage</a></h1>
-<p>In the simplest case, converting text to HTML works by creating an
-instance of <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt>, then calling it, passing a string and
-the name of a filter to use:</p>
-<pre class="literal-block">
-from template_utils.markup import MarkupFormatter
-formatter = MarkupFormatter()
-my_string = &quot;&quot;&quot;Lorem ipsum dolor sit amet.
-
-Consectetuer adipiscing elit.&quot;&quot;&quot;
-my_html = formatter(my_string, filter_name='markdown')
-</pre>
-<p>You can also pass arbitrary keyword arguments, and they will be handed
-off to the filter function; for example, to use Markdown's &quot;safe mode&quot;
-(which strips raw HTML before processing), you could call it like
-this:</p>
-<pre class="literal-block">
-my_html = formatter(my_string, filter_name='markdown', safe_mode=True)
-</pre>
-<p>The <tt class="docutils literal"><span class="pre">safe_mode=True</span></tt> argument will be handed directly to the
-<tt class="docutils literal"><span class="pre">markdown</span></tt> filter.</p>
-<p>To add a new filter, simply define it as a function; for example, to
-achieve the same effect as Django's built-in <tt class="docutils literal"><span class="pre">escape</span></tt> and
-<tt class="docutils literal"><span class="pre">linebreaks</span></tt> template filters, you could define this function:</p>
-<pre class="literal-block">
-def escape_linebreaks(text, **kwargs):
-    from django.utils.html import escape, linebreaks
-    return linebreaks(escape(text))
-</pre>
-<p>Filter functions must accept the string of text to convert as their
-first postional argument, and should accept <tt class="docutils literal"><span class="pre">**kwargs</span></tt> even if they
-don't do anything with it.</p>
-<p>To register the filter, simply call the <tt class="docutils literal"><span class="pre">register</span></tt> method of an
-instance of <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt>:</p>
-<pre class="literal-block">
-formatter.register('escape_linebreaks', escape_linebreaks)
-</pre>
-<p>The arguments to <tt class="docutils literal"><span class="pre">register</span></tt> are:</p>
-<blockquote>
-<ol class="arabic simple">
-<li>A string to use as the name of the filter.</li>
-<li>The filter function.</li>
-</ol>
-</blockquote>
-<p>Once the filter is registered, it can be used the same as the built-in
-filters:</p>
-<pre class="literal-block">
-my_html = formatter(my_string, filter_name='escape_linebreaks')
-</pre>
-<p><strong>Note:</strong> <tt class="docutils literal"><span class="pre">template_utils.markup</span></tt> creates an instance of
-<tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt>, called <tt class="docutils literal"><span class="pre">formatter</span></tt>; unless you have a need for
-multiple instances of <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt>, it's probably best to
-import and use that instance (by doing <tt class="docutils literal"><span class="pre">from</span> <span class="pre">template_utils.markup</span>
-<span class="pre">import</span> <span class="pre">formatter</span></tt>). This allows the single instance to be used in
-multiple places, and avoids the need to register any custom filter
-functions with multiple instances.</p>
-</div>
-<div class="section">
-<h1><a id="specifying-default-behavior-in-a-django-setting" name="specifying-default-behavior-in-a-django-setting">Specifying default behavior in a Django setting</a></h1>
-<p>To cut down on repetitive typing, <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt> can read a
-default filter name and keyword arguments from the Django setting
-<tt class="docutils literal"><span class="pre">MARKUP_FILTER</span></tt>; if you specify this setting, it should be a tuple
-with two elements:</p>
-<blockquote>
-<ol class="arabic simple">
-<li>The name of a filter to use.</li>
-<li>A dictionary of keyword arguments to pass to it.</li>
-</ol>
-</blockquote>
-<p>So to have Markdown with &quot;safe mode&quot; be the default behavior, you
-would add the following to your settings file:</p>
-<pre class="literal-block">
-MARKUP_FILTER = ('markdown', { 'safe_mode': True })
-</pre>
-<p>When you've specified <tt class="docutils literal"><span class="pre">MARKUP_FILTER</span></tt> in this way, you can perform
-text-to-html conversion just by passing in the string to convert, with
-no other arguments:</p>
-<pre class="literal-block">
-my_html = formatter(my_string)
-</pre>
-<p>The filter function specified in <tt class="docutils literal"><span class="pre">MARKUP_FILTER</span></tt> does not have to be
-in the default filter set; so long as you register a filter of the
-correct name before trying to do any text conversion, it will work.</p>
-<p>To have the default behavior apply no conversion at all, specify
-<cite>None</cite> as the filter name and an empty dictionary of keyword
-arguments:</p>
-<pre class="literal-block">
-MARKUP_FILTER = (None, {})
-</pre>
-<p><strong>Note:</strong> if you pass the <tt class="docutils literal"><span class="pre">filter_name</span></tt> keyword argument when
-performing text-to-HTML conversion, <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt> will
-completely ignore the <tt class="docutils literal"><span class="pre">MARKUP_FILTER</span></tt> setting (it won't even try to
-import the setting), so be sure to explicitly pass any keyword
-arguments you want to use. <tt class="docutils literal"><span class="pre">MarkupFormatter</span></tt> behaves this way so
-that it can be used stand-alone, without the need to configure or even
-install Django.</p>
-</div>
-<div class="section">
-<h1><a id="applying-text-to-html-conversion-in-templates" name="applying-text-to-html-conversion-in-templates">Applying text-to-HTML conversion in templates</a></h1>
-<p>A filter library called <tt class="docutils literal"><span class="pre">generic_markup</span></tt> is also included here, and
-it contains the filter <tt class="docutils literal"><span class="pre">apply_markup</span></tt>, which imports
-<tt class="docutils literal"><span class="pre">template_utils.markup.formatter</span></tt> and applies it to the text the
-filter is attached to:</p>
-<pre class="literal-block">
-{% load generic_markup %}
-{{ some_text|apply_markup %}
-</pre>
-<p>By itself, <tt class="docutils literal"><span class="pre">apply_markup</span></tt> will use the default behavior specified in
-<tt class="docutils literal"><span class="pre">MARKUP_FILTER</span></tt>, but it does accept a single argument which allows
-you to override the filter name:</p>
-<pre class="literal-block">
-{{ some_text|apply_markup:&quot;textile&quot; }}
-</pre>
-<p>This would have the same effect as the following Python code:</p>
-<pre class="literal-block">
-from template_utils.markup import formatter
-print formatter(some_text, filter_name='textile')
-</pre>
-<p>But remember that this will override <em>all</em> use of <tt class="docutils literal"><span class="pre">MARKUP_FILTER</span></tt>,
-so any custom keyword arguments you specified there will not be used
-when you pass an argument to <tt class="docutils literal"><span class="pre">apply_markup</span></tt>.</p>
-</div>
-</div>
-</body>
-</html>

File docs/overview.txt

-=========================
-Django template utilities
-=========================
-
-This is a small library of template tags and other template-related
-utilities for use with Django; while Django does a great job in
-general of helping developers avoid repetitive code, there are still a
-few things which tend to be useful or even needed in many different
-types of projects, so this application aims to genericize and bundle
-many of them into one reusable package.
-
-
-Downloading and installing
-==========================
-
-
-The easiest download method is a Subversion_ checkout; all of the code
-is maintained in a Subversion repository, and checking the code out
-from the repository makes it easy to handle updates. To download and
-install, simply execute this command from a directory that's on your
-Python path::
-
-    svn co http://django-template-utils.googlecode.com/svn/trunk/template_utils/
-
-This will create a directory called ``template_utils``, and download
-the current code into it. From there, you should be able to add
-``template_utils`` to the ``INSTALLED_APPS`` setting of any Django
-project and have it work. This application provides no models, so you
-don't need to run ``manage.py syncdb`` before using it.
-
-.. _Subversion: http://subversion.tigris.org/
-
-
-Feature overview
-================
-
-Currently, five main components are bundled into ``template_utils``:
-
-    * Template tags for `generic content retrieval`_.
-
-    * Template tags for `robust comparison operations`_.
-
-    * Template tags for `retrieving public comments`_ (for when a
-      comment-moderation system is in use).
-
-    * A `generic text-to-HTML conversion system`_ with template filter
-      support.
-
-    * A system for generating `template context processors`_ which can
-      add arbitrary settings to template contexts.
-
-.. _generic content retrieval: generic_content.html
-.. _robust comparison operations: comparison.html
-.. _retrieving public comments: public_comments.html
-.. _generic text-to-HTML conversion system: markup.html
-.. _template context processors: context_processors.html

File docs/public_comments.html

-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
-<title>Retrieving public comments</title>
-<style type="text/css">
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
-:Revision: $Revision: 4224 $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
-  border: 0 }
-
-table.borderless td, table.borderless th {
-  /* Override padding for "table.docutils td" with "! important".
-     The right padding separates the table cells. */
-  padding: 0 0.5em 0 0 ! important }
-
-.first {
-  /* Override more specific margin styles with "! important". */
-  margin-top: 0 ! important }
-
-.last, .with-subtitle {
-  margin-bottom: 0 ! important }
-
-.hidden {
-  display: none }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-blockquote.epigraph {
-  margin: 2em 5em ; }
-
-dl.docutils dd {
-  margin-bottom: 0.5em }
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
-  font-weight: bold }
-*/
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
-   compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
-  margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
-  margin-top: 0.5em }
-*/
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em ;
-  margin-right: 2em }
-
-div.footer, div.header {
-  clear: both;
-  font-size: smaller }
-
-div.line-block {
-  display: block ;
-  margin-top: 1em ;
-  margin-bottom: 1em }
-
-div.line-block div.line-block {
-  margin-top: 0 ;
-  margin-bottom: 0 ;
-  margin-left: 1.5em }
-
-div.sidebar {
-  margin-left: 1em ;
-  border: medium outset ;
-  padding: 1em ;
-  background-color: #ffffee ;
-  width: 40% ;
-  float: right ;
-  clear: right }
-
-div.sidebar p.rubric {
-  font-family: sans-serif ;
-  font-size: medium }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
-  margin-top: 0.4em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr.docutils {
-  width: 75% }
-
-img.align-left {
-  clear: left }
-
-img.align-right {
-  clear: right }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.attribution {
-  text-align: right ;
-  margin-left: 50% }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.rubric {
-  font-weight: bold ;
-  font-size: larger ;
-  color: maroon ;
-  text-align: center }
-
-p.sidebar-title {
-  font-family: sans-serif ;
-  font-weight: bold ;
-  font-size: larger }
-
-p.sidebar-subtitle {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option {
-  white-space: nowrap }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-span.section-subtitle {
-  /* font-size relative to parent (h1..h6 element) */
-  font-size: 80% }
-
-table.citation {
-  border-left: solid 1px gray;
-  margin-left: 1px }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.docutils {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.footnote {
-  border-left: solid 1px black;
-  margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap ;
-  padding-left: 0 }
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
-  font-size: 100% }
-
-tt.docutils {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="retrieving-public-comments">
-<h1 class="title">Retrieving public comments</h1>
-<p>Given the amount of comment spam on the Web, it's increasingly common
-for sites to employ some form of comment moderation; for example,
-comments posted more than 30 days after a weblog entry's publication
-might be non-public until approved by the entry's author, or comments
-might be submitted to Akismet and marked non-public if Akismet thinks
-they're spam.</p>
-<p>Django's bundled comments system provides the ability to have
-mdoerated comments via the <tt class="docutils literal"><span class="pre">is_public</span></tt> field on both the <tt class="docutils literal"><span class="pre">Comment</span></tt>
-and <tt class="docutils literal"><span class="pre">FreeComment</span></tt> models, but the built-in tags for retrieving lists
-of comments don't allow filtering on <tt class="docutils literal"><span class="pre">is_public</span></tt> or any other field;
-as a result, templates which display comment lists often have to
-include extra logic to weed out non-public comments.</p>
-<p>This library provides two tags which are nearly identical to Django's
-bundled <tt class="docutils literal"><span class="pre">get_comment_list</span></tt> and <tt class="docutils literal"><span class="pre">get_free_comment_list</span></tt> tags; the
-sole difference is that the tags included here will only retrive
-comments with <tt class="docutils literal"><span class="pre">is_public=True</span></tt>.</p>
-<p>To use these tags, you'll need to have <tt class="docutils literal"><span class="pre">template_utils</span></tt> in your
-<tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt> list, and you'll need to have <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span>
-<span class="pre">public_comments</span> <span class="pre">%}</span></tt> in your template.</p>
-<div class="section">
-<h1><a id="get-public-comment-list" name="get-public-comment-list"><tt class="docutils literal"><span class="pre">get_public_comment_list</span></tt></a></h1>
-<p>Like Django's built-in <tt class="docutils literal"><span class="pre">get_comment_list</span></tt>, this tag retrieves
-instances of <tt class="docutils literal"><span class="pre">django.contrib.comments.models.Comment</span></tt> (which
-requires registration and login to post) associated with a particular
-object, but this tag filters for <tt class="docutils literal"><span class="pre">is_public=True</span></tt>.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_public_comment_list for [app_name].[model_name] [object_id] as [varname] %}
-</pre>
-<p>Example:</p>
-<pre class="literal-block">
-{% get_public_comment_list for weblog.entry entry.id as comment_list %}
-</pre>
-<p>As with the <tt class="docutils literal"><span class="pre">get_comment_list</span></tt> tag, you can optionally pass an extra
-argument -- <tt class="docutils literal"><span class="pre">reversed</span></tt> -- at the end of the tag to get the list in
-reverse (i.e., newest comments first) order:</p>
-<pre class="literal-block">
-{% get_public_comment_list for weblog.entry entry.id as comment_list reversed %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="get-public-free-comment-list" name="get-public-free-comment-list"><tt class="docutils literal"><span class="pre">get_public_free_comment_list</span></tt></a></h1>
-<p>Like Django's built-in <tt class="docutils literal"><span class="pre">get_free_comment_list</span></tt>, this tag retrieves
-instances of <tt class="docutils literal"><span class="pre">django.contrib.comments.models.FreeComment</span></tt> (which
-allows anonymous commenting) associated with a particular object, but
-this tag filters for <tt class="docutils literal"><span class="pre">is_public=True</span></tt>.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_public_free_comment_list for [app_name].[model_name] [object_id] as [varname] %}
-</pre>
-<p>Example:</p>
-<pre class="literal-block">
-{% get_public_free_comment_list for weblog.entry entry.id as comment_list %}
-</pre>
-<p>As with the <tt class="docutils literal"><span class="pre">get_free_comment_list</span></tt> tag, you can optionally pass an
-extra argument -- <tt class="docutils literal"><span class="pre">reversed</span></tt> -- at the end of the tag to get the
-list in reverse (i.e., newest comments first) order:</p>
-<pre class="literal-block">
-{% get_public_free_comment_list for weblog.entry entry.id as comment_list reversed %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="get-public-comment-count" name="get-public-comment-count"><tt class="docutils literal"><span class="pre">get_public_comment_count</span></tt></a></h1>
-<p>Like Django's built-in <tt class="docutils literal"><span class="pre">get_comment_count</span></tt>, this tag returns the
-count of (registered) comments attached to an object, but it only
-counts comments which have <tt class="docutils literal"><span class="pre">is_public=True</span></tt>.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_public_comment_count for [app_name].[model_name] [object_id] as [varname] %}
-</pre>
-<p>Example:</p>
-<pre class="literal-block">
-{% get_public_comment_count for weblog.entry entry.id as  comment_list %}
-</pre>
-</div>
-<div class="section">
-<h1><a id="get-public-free-comment-count" name="get-public-free-comment-count"><tt class="docutils literal"><span class="pre">get_public_free_comment_count</span></tt></a></h1>
-<p>Like Django's built-in <tt class="docutils literal"><span class="pre">get_free_comment_count</span></tt>, this tag returns
-the count of (unregistered) comments attached to an object, but it
-only counts comments which have <tt class="docutils literal"><span class="pre">is_public=True</span></tt>.</p>
-<p>Syntax:</p>
-<pre class="literal-block">
-{% get_public_free_comment_count for [app_name].[model_name] [object_id] as [varname] %}
-</pre>
-<p>Example:</p>
-<pre class="literal-block">
-{% get_public_free_comment_count for weblog.entry entry.id as  comment_list %}
-</pre>
-</div>
-</div>
-</body>
-</html>
+from distutils.core import setup
+
+setup(name='template_utils',
+      version='0.1',
+      description='Template-related utilities for Django applications',
+      author='James Bennett',
+      author_email='james@b-list.org',
+      url='http://code.google.com/p/django-template-utils/',
+      packages=['template_utils', 'template_utils.templatetags'],
+      classifiers=['Development Status :: 4 - Beta',
+                   'Environment :: Web Environment',
+                   'Intended Audience :: Developers',
+                   'License :: OSI Approved :: BSD License',
+                   'Operating System :: OS Independent',
+                   'Programming Language :: Python',
+                   'Topic :: Utilities'],
+      )