From a3942c1d057b55f02c0890ae83f19e723df663ba Mon Sep 17 00:00:00 2001
From: "Dustin J. Mitchell" <dustin@zmanda.com>
Date: Sun, 7 Mar 2010 14:31:54 -0600
Subject: [PATCH] add developer note about jinja whitespace

---
 docs/developer.texinfo | 45 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/developer.texinfo b/docs/developer.texinfo
index b1c7d2a6bdf..3cac184e5a9 100644
--- a/docs/developer.texinfo
+++ b/docs/developer.texinfo
@@ -17,6 +17,7 @@ described here.
 * The Event Loop::
 * String Types::
 * Subscription Interfaces::
+* Jinja Web Templates::
 * Twisted Idioms::
 * Testing Idioms and Utilities::
 * Developer Class Index::
@@ -232,6 +233,50 @@ TODO
 
 TODO use @code{buildbot.eventually}
 
+@node Jinja Web Templates
+@section Jinja Web Templates
+
+Buildbot uses Jinja2 to render its web interface.  The authoritative source for
+this templating engine is @uref{http://jinja.pocoo.org/2/documentation/, its
+own documentation}, of course, but a few notes are in order for those who are
+making only minor modifications.
+
+@heading Whitespace
+
+Jinja directives are enclosed in @code{@{% .. %@}}, and sometimes also have
+dashes.  These dashes strip whitespace in the output.  For example:
+
+@example
+@{% for entry in entries %@}
+  <li>@{@{ entry @}@}</li>
+@{% endfor %@}
+@end example
+
+will produce output with too much whitespace:
+
+@example
+
+  <li>pigs</li>
+
+
+  <li>cows</li>
+
+@end example
+
+But adding the dashes will collapse that whitespace completely:
+
+@example
+@{% for entry in entries -%@}
+  <li>@{@{ entry @}@}</li>
+@{%- endfor %@}
+@end example
+
+yields
+
+@example
+<li>pigs</li><li>cows</li>
+@end example
+
 @node Twisted Idioms
 @section Twisted Idioms