PageTemplate 2.1.3 → 2.1.5

data/Changes

@@ -1,4 +1,4 @@
-2.1.3:
+CVS:
     Bugfixes:
       HTGlossary didn't survive the change from 2.0 to 2.1. I've
           added unit tests and fixed the HTGlossary bugs. Whoops.

data/Rakefile

@@ -54,7 +54,7 @@ end
 
 spec = Gem::Specification.new do |s|
   s.name = "PageTemplate"
-  s.version = "2.1.3"
+  s.version = "2.1.5"
   s.author = "Brian Wisti"
   s.email  = "brianwisti@rubyforge.org"
   s.homepage = "http://coolnamehere.com/products/pagetemplate"

data/lib/PageTemplate/parser.rb

@@ -176,11 +176,20 @@ class PageTemplate
   class FileSource < Source
     attr_reader :paths
 
+    # initialize looks for the following in the args Hash:
+    #  * include_paths = a list of file paths
+    #  * include_path  = a single file path string 
+    #                    (kept for backwards compatibility)
     def initialize(args = {})
       @args  = args
-      @paths = @args['include_paths']
-      @paths ||= [@args['include_path']].compact
-      @paths = [Dir.getwd,'/'] if @paths.empty?
+      if @args['include_paths']
+        @paths = @args['include_paths']
+      elsif @args['include_path']
+        @paths = [ @args['include_path'] ]
+      else
+        @paths = [Dir.getwd,'/']
+      end
+      @paths = @paths.compact
       @cache = Hash.new(nil)
       @mtime = Hash.new(0)
     end
@@ -204,20 +213,16 @@ class PageTemplate
         return "[ Unable to open file #{fn} because of #{er.message} ]"
       end
     end
-
     def cache(name,cmds)
       fn = get_filename(name)
       @cache[fn] = cmds.dup
       @mtime[fn] = Time.now.to_i
     end
-
-    # Return the absolute pathname of the first name +file+
-    # found in the include_paths.
     def get_filename(file)
       file = file.gsub(/\.\.\//,'') 
-      file.untaint
       @paths.each do |path|
         fn = File.join(path,file)
+        fn.untaint
         return fn if File.exists?(fn)
       end
       return nil

data/setup-usage.txt

@@ -4,7 +4,7 @@ Installing Programs with setup.rb
 Quick Start
 -----------
     
-  Type this (You might needs super user privilege):
+  Type this (You might needs super user previledge):
 
       ($ su)
        # ruby setup.rb

data/site/Makefile

@@ -0,0 +1,15 @@
+all: site css
+css:
+	cp base.css html/
+site:
+	ruby Site.rb
+images: site
+	mkdir html/images
+	cp extras/images/* html/images/
+doc:
+	cp -R extras/doc/PageTemplate html/doc
+clean:
+	rm -rf html
+
+test-install:
+	sudo cp -Rf html/* /var/www/html

data/site/MySubpageRenderer.rb

@@ -0,0 +1,43 @@
+require 'ZenWeb/GenericRenderer'
+
+=begin
+
+= Class SubpageRenderer
+
+Generates a list of known subpages in a format compatible with
+TextToHtmlRenderer.
+
+=== Methods
+
+=end
+
+class MySubpageRenderer < GenericRenderer
+
+=begin
+
+     --- SubpageRenderer#render(content)
+
+     Renders a list of known subpages in a format compatible with
+     TextToHtmlRenderer. Adds the list to the end of the content.
+
+=end
+
+  def render(content)
+    subpages = @document.subpages.clone
+    if (subpages.length > 0) then
+      push("\n\n")
+      push("<h2>Subpages:</h2>\n\n")
+      subpages.each_index { | index |
+	url      = subpages[index]
+	doc      = @website[url]
+	title    = doc.fulltitle
+
+	push("* <A HREF=\"#{url}\">#{title}</A>\n")
+      }
+      push("\n")
+    end
+
+    return content + self.result
+  end
+end
+

data/site/PageNavRenderer.rb

@@ -0,0 +1,37 @@
+require 'ZenWeb/GenericRenderer'
+
+class PageNavRenderer < GenericRenderer
+  def render(content)
+    # I know there's a quicker way to do this, but I'm in a hurry.
+    this_url = @document.url
+    doc_order = @sitemap.doc_order
+    this_index = doc_order.index(this_url)
+    forward = backward = " "
+
+    last_url = doc_order[this_index - 1]
+    last_page = @sitemap.documents[last_url]
+    if last_page and File.dirname(last_url) == File.dirname(this_url)
+      title = last_page.title
+      url = File.basename(last_url)
+      backward = "<p>&lt;- <a href='#{url}'>#{title}</a></p>\n"
+    end
+
+    next_url = doc_order[this_index + 1]
+    next_page = @sitemap.documents[next_url]
+    if next_page and File.dirname(next_url) == File.dirname(this_url)
+      title = next_page.title
+      url = File.basename(next_url)
+      forward = "<p><a href='#{url}'>#{title}</a>- &gt;</p>\n"
+    end
+
+    push("<table width='100%' border='0'><tr>\n")
+    push("<td>#{backward}</td>\n")
+    push("<td align='right'>#{forward}</td>\n")
+    push("</tr></table>\n")
+
+    push(content)
+
+    return self.result
+  end
+end
+

data/site/RedClothRenderer.rb

@@ -0,0 +1,20 @@
+require 'ZenWeb/GenericRenderer'
+
+# Hands content off to the RedCloth text formatter for rendering.
+#
+# + Set Attributes in the 'RedClothAttributes' metadata.
+#     + filter_html   -- HTML not created by RedCloth is escaped
+#     + filter_styles -- style markup specifier is disabled
+# + See http://www.whytheluckystiff.net/ruby/redcloth/
+class RedClothRenderer < GenericRenderer
+  require 'redcloth'
+  
+  def render(content)
+    attributes = []
+    if @document.metadata.has_key?('RedClothAttributes')
+      attributes = @document['RedClothAttributes']
+    end
+    rc = RedCloth::new(content, attributes)
+    return rc.to_html(:textile)
+  end
+end

data/site/Site.rb

@@ -0,0 +1,11 @@
+#!/usr/local/bin/ruby
+
+require 'ZenWeb'
+
+data_dir = "src"
+html_dir = "html"
+sitemap  = "/SiteMap.html"
+url      = "/"
+
+website = ZenWebsite.new(sitemap, data_dir, html_dir)
+website.renderSite

data/site/SiteNewsRenderer.rb

@@ -0,0 +1,23 @@
+require 'ZenWeb/GenericRenderer'
+
+class SiteNewsRenderer < GenericRenderer
+  require 'yaml'
+
+  def render(content)
+    newsfile = 'news.yml'
+    newsitems = YAML.load(File.open(newsfile).read())
+    limit = @document['NewsLimit']
+
+    if newsitems
+      newsitems.each do |item|
+        push("\n<div class='newsitem'>\n\nh3. #{item['title']}\n\np(date). #{item['date']}\n\n#{item['content']}\n</div>\n")
+        if limit
+          limit -= 1
+          break if limit == 0
+        end
+      end
+    end
+
+    return self.result
+  end
+end

data/site/XhtmlTemplateRenderer.rb

@@ -0,0 +1,141 @@
+require 'ZenWeb/HtmlRenderer'
+
+=begin
+
+= Class HtmlTemplateRenderer
+
+Generates a consistant HTML page header and footer, including a
+navigation bar, title, subtitle, and appropriate META tags.
+
+=== Methods
+
+=end
+
+class XhtmlTemplateRenderer < HtmlRenderer
+
+=begin
+
+--- HtmlTemplateRenderer#render(content)
+
+    Renders a standardized HTML header and footer. This currently also
+    includes a navigation bar and a list of subpages, which will
+    probably be broken out to their own renderers soon.
+
+    Metadata variables used:
+
+    + author
+    + banner - graphic at the top of the page, usually a logo
+    + bgcolor - defaults to not being defined
+    + copyright
+    + description
+    + dtd (default: 'DTD HTML 4.0 Transitional')
+    + email - used in a mailto in metadata
+    + keywords
+    + rating (default: 'general')
+    + stylesheet - reference to a CSS file
+    + style - CSS code directly (for smaller snippets)
+    + subtitle
+    + title (default: 'Unknown Title')
+    + icbm - longitude and latitude for geourl.org
+    + icbm_title - defaults to the page title
+
+=end
+
+  def render(content)
+    author      = @document['author']
+    banner      = @document['banner']
+    bgcolor     = @document['bgcolor']
+    dtd		= @document['dtd'] || 'DTD HTML 4.0 Transitional'
+    copyright   = @document['copyright']
+    description = @document['description']
+    email       = @document['email']
+    keywords    = @document['keywords']
+    rating      = @document['rating'] || 'general'
+    stylesheet  = @document['stylesheet']
+    subtitle    = @document['subtitle']
+    title       = @document['title'] || 'Unknown Title'
+    icbm        = @document['icbm']
+    icbm_title  = @document['icbm_title'] || @document['title']
+    charset     = @document['charset']
+    style       = @document['style']
+
+    titletext   = @document.fulltitle
+
+    # TODO: iterate over a list of metas and add them in one nicely organized block
+
+    # header
+    push([
+	   '<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">',
+	   "<head>\n",
+	   "<title>#{titletext}</title>\n",
+	   stylesheet ? "<link rel=\"STYLESHEET\" href=\"#{stylesheet}\" type=\"text/css\" title=\"#{stylesheet}\">\n" : [],
+	   style ? "<style>\n#{style}\n</style>" : [],
+	   "</head>\n",
+	   "<body>\n"
+	 ])
+
+    self.navbar
+
+    if banner then
+      push("<img src=\"#{banner}\" /><br />\n")
+      unless (subtitle) then
+	push("<h3>#{title}</h3>\n")
+      end
+    else
+      push("<h1>#{title}</h1>\n")
+    end
+
+    push([
+	   subtitle ? "<h2>#{subtitle}</h2>\n" : [],
+	   "<hr />\n\n",
+	   content,
+	   "<hr />\n\n",
+	 ])
+
+    self.navbar
+
+    push("\n</body>\n</html>\n")
+
+    return self.result
+  end
+
+=begin
+
+--- HtmlTemplateRenderer#navbar
+
+    Generates a navbar that contains a link to the sitemap, search
+    page (if any), and a fake "breadcrumbs" trail which is really just
+    a list of all of the parent titles up the chain to the top.
+
+=end
+
+  def navbar
+
+    sep = " / "
+    search  = @website["/Search.html"]
+
+    push([
+	   "<p class=\"navbar\">\n",
+	   "<a href=\"#{@sitemap.url}\">Sitemap</a>",
+	   search ? " | <a href=\"#{search.url}\"><em>Search</em></a>" : [],
+	   " || ",
+	 ])
+
+    path = []
+    current = @document
+    while current and current != current.parent do
+      current = current.parent
+      path.unshift(current) if current
+    end
+
+    push([
+	   path.map{|doc| ["<a href=\"#{doc.url}\">#{doc['title']}</a>\n", sep]},
+	   @document['title'],
+	   "</p>\n",
+	 ])
+
+    return []
+  end
+
+end
+

data/site/base.css

@@ -0,0 +1,4 @@
+body {
+    background-color: white;
+    color: black;
+}

data/site/footer.txt

@@ -0,0 +1,2 @@
+<hr />
+<p>Copyright 2002 - 2005 Brian Wisti and Greg Millam</p>

data/site/header.txt

@@ -0,0 +1,2 @@
+<h1>PageTemplate</h1>
+<hr />

data/site/html/SiteMap.html

@@ -0,0 +1,43 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+<TITLE>SiteMap: There are 6 pages in this website.</TITLE>
+<LINK REL="STYLESHEET" HREF="base.css" type="text/css" title="base.css">
+<META NAME="rating" CONTENT="general">
+<META NAME="GENERATOR" CONTENT="ZenWeb v. 2.17.0 http://www.zenspider.com/ZSS/Products/ZenWeb/">
+<META NAME="keywords" CONTENT="sitemap, website">
+<META NAME="description" CONTENT="This page links to every page in the website.">
+<link rel="up" href="index.html" title="PageTemplate">
+<link rel="contents" href="" title="SiteMap">
+<link rel="top" href="index.html" title="PageTemplate">
+</HEAD>
+<BODY>
+<h1>Yo!</h1>
+<hr />
+<P class="navbar">
+<A HREF="">Sitemap</A> || <A HREF="index.html">PageTemplate</A>
+ / SiteMap</P>
+<H1>SiteMap</H1>
+<H2>There are 6 pages in this website.</H2>
+<HR SIZE="3" NOSHADE>
+
+<UL>
+  <LI><A HREF="index.html">PageTemplate</A></LI>
+  <LI><A HREF="install.html">Getting It</A></LI>
+  <LI><A HREF="designer.html">The Designer's Perspective</A></LI>
+  <LI><A HREF="programmer.html">The Programmer's Perspective</A></LI>
+  <LI><A HREF="version2.html">PageTemplate Version 2: What's New?</A></LI>
+  <LI><A HREF="">SiteMap: There are 6 pages in this website.</A></LI>
+</UL>
+<HR SIZE="3" NOSHADE>
+
+<P class="navbar">
+<A HREF="">Sitemap</A> || <A HREF="index.html">PageTemplate</A>
+ / SiteMap</P>
+
+<h1>Yo!</h1>
+<hr />
+<h1>Yo!</h1>
+<hr />
+</BODY>
+</HTML>

data/site/html/base.css

@@ -0,0 +1,4 @@
+body {
+    background-color: white;
+    color: black;
+}

data/site/html/designer.html

@@ -0,0 +1,524 @@
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
+<title>The Designer's Perspective</title>
+<link rel="STYLESHEET" href="base.css" type="text/css" title="base.css">
+</head>
+<body>
+<h1>Yo!</h1>
+<hr />
+<p class="navbar">
+<a href="SiteMap.html">Sitemap</a> || <a href="index.html">PageTemplate</a>
+ / The Designer's Perspective</p>
+<h1>The Designer's Perspective</h1>
+<hr />
+
+<table width='100%' border='0'><tr>
+<td><p>&lt;- <a href='install.html'>Getting It</a></p>
+</td>
+<td align='right'><p><a href='programmer.html'>The Programmer&#8217;s Perspective</a>- &gt;</p>
+</td>
+</tr></table>
+
+	<h2>Who Are You?</h2>
+
+
+	<p>You are the esteemed Web Designer, aesthetically talented and
+perhaps artistically inclined. You know what makes a good Web page.
+You are not a programmer, though. It&#8217;s horrible when you have to go
+down to the caves where they keep the developers to explain
+where a simple login form belongs. You also don&#8217;t want to 
+remember where their odd-looking programming code is supposed to go
+in your beautiful page. You want a simple, clean way of describing
+the dynamic elements of site pages.</p>
+
+
+	<p>Okay, I&#8217;ve had too much coffee. This page explains how templating
+works, and how to put PageTemplate to use when laying out the <span class="caps">HTML</span>
+of your page.</p>
+
+
+	<h2>What&#8217;s a Template?</h2>
+
+
+	<p>When you are designing pages for a dynamic site or Web application,
+there are a lot of details you won&#8217;t know in advance. Some examples
+might include login information, the contents of a shopping cart, 
+or maybe even the contents of the page! Templates
+allow you to put placeholders within your <span class="caps">HTML</span> to show where that login
+information is displayed and how it is formatted. A good template
+system does not require you to remember code while you&#8217;re designing:
+you just make the page, and let programmers worry about filling it with
+data.</p>
+
+
+	<p>In PageTemplate, those placeholders are referred to as <em>directives</em>.</p>
+
+
+	<h2>How Do I Use PageTemplate In My Pages?</h2>
+
+
+	<p>PageTemplate uses a simple language which you can embed
+in your page. You should be able to use your favorite design tools to
+create an attractive template. My favorite design tool happens to be
+<a href="geekery/editors/emacs/index.html">GNU/Emacs</a>, but the odds are that 
+the designers out there lean towards something a little friendlier, like 
+<a href="http://www.dreamweaver.com/">Macromedia Dreamweaver</a>. With the default syntax, 
+all of us can be happy.</p>
+
+
+	<p>PageTemplate directives are indicated by being wrapped in between
+<code>[%</code> and <code>%]</code> characters. If any of those characters are missing, PageTemplate 
+decides it is not a directive, and leaves it alone.</p>
+
+
+	<h3>Variables</h3>
+
+
+	<p>The major directives require <em>variables</em>, which are just
+names for the value your want inserted, checked, or otherwise
+accessed. It&#8217;s a good idea to use variable names that make
+sense (<code>name</code> for a person&#8217;s name, <code>title</code> for the title of the page, etc.).</p>
+
+
+	<h3>Value Substitution</h3>
+
+
+	<p>Substitution is the easiest concept to master. When PageTemplate
+comes across a value directive, it replaces that directive with some text.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>
+[%var variable %]
+</pre>
+
+	<h4>Example</h4>
+
+
+<pre>
+&lt;h1&gt;Hello, [%var name %]&lt;/h1&gt;
+</pre>
+
+	<p>Every time that PageTemplate sees <code>[%var name %]</code> in
+your template, it will replace that directive with the text 
+associated with <code>name</code>.</p>
+
+
+	<p>The programmer works his magic, and the visitor &#8220;Frank&#8221; sees this
+greeting:</p>
+
+
+<pre>&lt;h1&gt;Hello, Frank&lt;/h1&gt;</pre>
+
+	<p>If <code>name</code> is not set, nothing is inserted. The greeting header would end up 
+looking like this:</p>
+
+
+<pre>&lt;h1&gt;Hello, &lt;/h1&gt;</pre>
+
+	<h3>If</h3>
+
+
+	<p>The <code>if</code> directive tells PageTemplate to only display a chunk of content when 
+some condition is true. If the condition is not true, PageTemplate skips the 
+block and moves on.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>
+[%if condition %]
+chunk
+[%endif%]
+</pre>
+
+	<h4>Example</h4>
+
+
+<pre>
+[%if pageowner%]
+&lt;a href="admin.cgi"&gt;Admin&lt;/a&gt;
+[%endif%]
+</pre>
+
+	<p>In this example, if the application tells PageTemplate that 
+<code>pageowner</code> is true, PageTemplate inserts a link to 
+an administrative page. Otherwise, nothing happens here.</p>
+
+
+	<h3>If/Else</h3>
+
+
+	<p>The <code>else</code> directive adds extra power to <code>if</code>, by indicating a chunk of 
+content to use when a condition is not true.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>
+[%if value%] 
+chunk 
+[%else%]
+alternate chunk
+[%endif%]
+</pre>
+
+	<h4>Example</h4>
+
+
+<pre>
+[%if login%]
+&lt;p&gt;Welcome back, [%var login%]!&lt;/p&gt;
+&lt;p&gt;&lt;a href="logout.cgi"&gt;Log Out&lt;/a&gt;&lt;/p&gt;
+[%else%]
+&lt;form name="login" method="post"&gt;
+Login: &lt;input type="text" name="login" /&gt;&lt;br /&gt;
+Password: &lt;input type="password" name="passwd" /&gt;&lt;br /&gt;
+&lt;input type="submit" value="Login" /&gt;
+[%endif%]
+</pre>
+
+	<p>This is the situation where I use <code>else</code> directives the
+most. If the visitor is logged in to a Web application, she
+is shown a brief welcoming message. If not, then she will see a
+login form.</p>
+
+
+	<p>This example also shows a convenient approach to <code>if</code>
+conditions. We <em>could</em> make up a special <code>logged_in</code>
+variable, but since all we care about here is the presence of a login,
+we have PageTemplate test that as if it were a regular condition.</p>
+
+
+	<h3>Unless</h3>
+
+
+	<p>Sometimes you only want to display a chunk if something is false, but
+nothing if the condition is true. That description twisted my brain
+a little bit. Think of it this way. Sometimes it&#8217;s just easier to say
+&#8220;unless something&#8221; instead of &#8220;if not_something&#8221;. That&#8217;s all. Templates
+should be easy to read, you know? That&#8217;s what this directive is for:
+making some of the logic in your template easier to read.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>
+[%unless condition %]
+chunk
+[%end unless%]
+</pre>
+
+	<h4>Example</h4>
+
+
+<pre>
+[%unless launched%]
+Product Launch Coming Soon!
+[%end unless%]
+</pre>
+
+	<h3>In</h3>
+
+
+	<p>Use the <code>in</code> directive when you want PageTempate to insert the same chunk 
+repeatedly for a list of items. It can grab values from the item to be 
+inserted in <code>value</code> directives within the chunk. If there is no list of items, 
+the <code>in</code> chunk is skipped.</p>
+
+
+	<p>The <code>in</code> directive is the most complex, and requires more explanation of its 
+details.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>
+[%in list%]
+some text and [%var value%]
+[%end in%]
+</pre>
+
+	<h4>Example</h4>
+
+
+<pre>
+&lt;ul&gt;
+[%in books%]
+  &lt;li&gt;"[%var title%]" by [%var author%]&lt;/li&gt;
+[%end in%]
+&lt;/ul&gt;
+</pre>
+
+	<p>It presents a list of favorite albums, along with the band that produced it. 
+If there was no such list, then PageTemplate would not insert anything, and
+we would be left with <code>&lt;ul&gt;&lt;/ul&gt;</code> all by itself. 
+That&#8217;s more than a little awkward from a designer&#8217;s point of view, but
+the <code>no</code> directive presentd in a few moments helps us work around that.</p>
+
+
+	<h4>&#8220;Local&#8221; Values</h4>
+
+
+	<p>When stepping through a list, PageTemplate works a little magic with
+<code>value</code> directives. First it examines the list item to see
+if it has a value for the variable named. If it can&#8217;t find one there,
+it checks its main variable listing and tries to insert that. If it
+can&#8217;t find a value in the main variable listing, it inserts nothing for
+that <code>value</code> directive.</p>
+
+
+This logic works for nested lists, too. If you have an 
+<code>in</code> directive embedded in another <code>in</code> directive,
+(say, a list of books written by each one of a list of your favorite
+authors), PageTemplate first looks in the innermost list (the books) for
+a name, then the next list out (the authors), and finally the main
+variable listing.
+
+	<h4>Loop Metavariables</h4>
+
+
+	<p><em>Metavariables</em> were added in 1.2 so that you can fine-tune your lists, loops, and tables. They are special
+flags that are set during certain times in a loop: the first time through, the last time through, during
+odd trips through the loop, etcetera. Metavariables are uppercased and wrapped in double underscores to
+emphasize that they are not normal variables.</p>
+
+
+	<p>Here are all of the metavariables that are defined in <code>in</code> blocks.</p>
+
+
+	<table>
+		<tr>
+			<th>variable  </th>
+			<th>description </th>
+		</tr>
+		<tr>
+			<td> <code>__FIRST__</code> </td>
+			<td> true if this is the first time through the loop. </td>
+		</tr>
+		<tr>
+			<td> <code>__LAST__</code>  </td>
+			<td> true if this is the last time through the loop. </td>
+		</tr>
+		<tr>
+			<td> <code>__ODD__</code>   </td>
+			<td> true on odd-numbered steps through the loop (1st, 3rd, 5th) </td>
+		</tr>
+	</table>
+
+
+
+
+	<p>And to give a little idea of metavariables in action, here&#8217;s a little example:</p>
+
+
+<pre>
+&lt;table&gt;
+&lt;tr&gt;&lt;th&gt;#&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;th&gt;Amount&lt;/th&gt;&lt;/tr&gt;
+[%in transactions %]
+[%if __ODD__ %]
+&lt;tr class="odd"&gt;
+[%else%]
+&lt;tr&gt;
+[%endif%]
+  &lt;td&gt;[%var num%]&lt;/td&gt;
+  &lt;td&gt;[%var description%]&lt;/td&gt;
+  &lt;td&gt;[%var amount%]
+&lt;/tr&gt;
+[%endin%]
+&lt;/table&gt;
+</pre>
+
+	<h3>In/No</h3>
+
+
+	<p>The <code>no</code> directive allows you to use an alternate chunk
+for an <code>in</code> if there is no list available.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>
+[%in list%]
+  [%var value%]
+[%no%]
+  Nothing in the list
+[%endin%]
+</pre>
+
+	<h4>Example</h4>
+
+
+<pre>
+&lt;ul&gt;
+[%in books%]
+  &lt;li&gt;"[%var title%]" by [%var author%]&lt;/li&gt;
+[%no%]
+  &lt;li&gt;I have no favorites today.&lt;/li&gt;
+[%endin%]
+&lt;/ul&gt;
+</pre>
+
+	<p>This extends the earlier example by providing an alternate chunk
+to use if there is no list named <code>books</code>. Now
+the <acronym title="Hypertext Markup Language"><span class="caps">HTML</span></acronym> 
+formatting is a little more appropriate. Instead of displaying
+an empty list, it shows a list item declaring that there is no list.</p>
+
+
+	<p>I think I hurt my head with that last sentence.</p>
+
+
+	<h4>Lists and <span class="caps">WYSIWYG </span>Editors</h4>
+
+
+	<p>Here&#8217;s a specific problem that might pop up when you are using
+a <acronym title="What You See Is What You Get"><span class="caps">WYSIWYG</span></acronym>
+editor. Let&#8217;s say you&#8217;re embedding a list into a table, so that each
+item in the list gets one table row. Dreamweaver is probably not
+going to like this style:</p>
+
+
+<pre>
+&lt;table&gt;
+[%in listing%]
+  &lt;tr&gt;
+    &lt;td&gt;[%var item%]&lt;/td&gt;
+  &lt;/tr&gt;
+[%no%]
+  &lt;tr&gt;
+    &lt;td&gt;Listing is empty&lt;/td&gt;
+  &lt;/tr&gt;
+[%endin%]
+&lt;/table&gt;
+</pre>
+
+	<p>The problem is that the <code>in listing</code>, <code>no</code>,
+and <code>endin</code> directives are in locations that make for 
+invalid <span class="caps">HTML</span>, and might not be allowed by your editor.</p>
+
+
+	<p>It turns out that the solution is simple, though maybe a little
+awkward. Wrap the offending directives in <span class="caps">HTML</span> comments, like this
+example shows:</p>
+
+
+<pre>
+&lt;table&gt;
+&lt;!-- [%in listing%] --&gt;
+  &lt;tr&gt;
+    &lt;td&gt;[%var item%]&lt;/td&gt;
+  &lt;/tr&gt;
+&lt;!-- [%no%] --&gt;
+  &lt;tr&gt;
+    &lt;td&gt;Listing is empty&lt;/td&gt;
+  &lt;/tr&gt;
+&lt;!-- [%endin%] --&gt;
+&lt;/table&gt;
+</pre>
+
+	<p>Your fancy editor should be able to handle this, and PageTemplate
+should be able to understand it just fine. The only side effect
+is that you will have some empty comments in your final page.</p>
+
+
+	<p>The other solution is to use <a href="geekery/editors/vim/index.html">Vim</a>,
+<a href="http://www.xemacs.org/">XEmacs</a>, or some other effective 
+non-<acronym title="What You See Is What You Get"><span class="caps">WYSIWYG</span></acronym>
+editor. Personal preference, of course. I know that Dreamweaver and GoLive 
+cost good money, and you aren&#8217;t going to toss them aside just because I say 
+so. Hopefully this workaround will suit your needs.</p>
+
+
+	<h3>Include</h3>
+
+
+	<p>The <code>include</code> directive is very simple to use, but it gives you a whole lot of
+extra power. It allows you to include content that comes from another
+files, including templates. This can be useful when building a page out of 
+smaller component templates.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>[%include filename %]</pre>
+
+	<p><code>filename</code> can point to a real file in a particular directory, or it could be a
+placeholder variable name. If PageTemplate can&#8217;t find that file, it displays a simple message stating
+that the file was not found. The idea for this is to make it easier for developers to debug problems during
+testing, rather than for you to wonder why there&#8217;s a blank space where your menu text should be.</p>
+
+
+	<h4>Example</h4>
+
+
+<pre>
+[%include menu %]
+</pre>
+
+	<p>Meanwhile, we have something like this in <em>menu.txt</em></p>
+
+
+<pre>
+&lt;table&gt;
+[%in photos%]
+  &lt;tr&gt;
+    &lt;td&gt;[%var title%]&lt;/td&gt;
+    &lt;td&gt;[%var thumbnail %]&lt;/td&gt;
+  &lt;/tr&gt;
+[%endin%]
+&lt;/table&gt;
+</pre>
+
+	<p>Do you see what I meant when I said &#8220;simple&#8221;? If not, then please let me know.
+I&#8217;m still working on this part of the manual.</p>
+
+
+	<h3>Comments</h3>
+
+
+	<p>Every once in a while you want to make a comment about your template, but not have it show up the 
+<span class="caps">HTML</span> markup that goes to the visitor. Comments are perfect for that. They are eaten up and spit aside
+by PageTemplate when reading your template file, and the visitor never sees them.</p>
+
+
+	<h4>Syntax</h4>
+
+
+<pre>
+[%-- comment --%]
+</pre>
+
+	<h2>Customized Syntax</h2>
+
+
+	<p>One of PageTemplate&#8217;s features is the ability to come up with your
+own directive syntax. If you feel that the default syntax is
+less than ideal, discuss a new system with your developers. If
+you are the lone designer/developer, talk to yourself for a bit. We
+all need some quality time to ourselves occasionally. Working together,
+you and the developers <em>(or you and your split personalities)</em>
+can come up with a syntax that is much more comfortable.</p>
+
+
+	<h2>Conclusion</h2>
+
+
+	<p>Yes, we&#8217;ve already reached the end of this designer&#8217;s tutorial.
+Now go make with the pretty pages!</p><hr />
+
+<p class="navbar">
+<a href="SiteMap.html">Sitemap</a> || <a href="index.html">PageTemplate</a>
+ / The Designer's Perspective</p>
+
+<h1>Yo!</h1>
+<hr />
+</body>
+</html>