--- a/README.txt	Mon Feb 08 11:40:57 2010 -0500
+++ b/README.txt	Mon Feb 08 11:44:20 2010 -0500
@@ -63,16 +63,46 @@
 at [decoupage.formatters]).  For example: /include = site.html could
 include the site.html genshi template at the top of the body.
 
+Formatters:
+
+sort: 
+    determines how to sort the files in a directory; 
+    right now only by case-insensitive alphabetically
+    * reverse : reverse the order of the sorting
+    
 all: 
     only pass files of a certain pattern; 
     the inverse of ignore
     calling all with no arguments means only files with descriptions
     are used
     
-title: splits a description into a title and a description with a
-separator
-describe: substitute the description for the filename
-ignore: ignore files of a certain pattern
+title: 
+    splits a description into a title and a description via a
+    separator in 
+    the description.  The template will now have an additional
+    variable, 
+    'title', per file
+    Arguments:
+    * separator: what separator to use (':' by default)
+    
+describe: 
+    obtain the description from the filename
+    the file extension (if any) will be dropped and
+    spaces will be substituted for underscores
+    
+ignore: 
+    ignore files of a glob patterns.  
+    These files will not be linked to in the template.
+    e.g. /ignore = .* *.pdf  # don't list dotfiles and PDFs
+    
 include: include a file at the top of the body
-css: specify CSS
+css: specify CSS used (whitespace separated list)
+
+Decoupage also makes use of other special intrinsic keywords:
 
+formatters: ordered list of formatters to apply
+
+inherit: inherit configuration from a certain directory (instead of
+the parent
+
+transform: a list of transformers for contenttransformer

--- a/decoupage/formatters.py	Mon Feb 08 11:40:57 2010 -0500
+++ b/decoupage/formatters.py	Mon Feb 08 11:44:20 2010 -0500
@@ -35,7 +35,11 @@
 ### formatters
 
 class Ignore(object):
-    """ignore files of a certain pattern"""
+    """
+    ignore files of a glob patterns.  
+    These files will not be linked to in the template.
+    e.g. /ignore = .* *.pdf  # don't list dotfiles and PDFs
+    """
 
     def __init__(self, ignore):
         self.match = ignore.split()
@@ -76,7 +80,11 @@
         data['files'] = _files
         
 class Sort(object):
-    """ determines how to sort the files in a directory """
+    """
+    determines how to sort the files in a directory; 
+    right now only by case-insensitive alphabetically
+    * reverse : reverse the order of the sorting
+    """
     def __init__(self, pattern):
         self.args = [i.strip() for i in pattern.split(',')]
     
@@ -89,13 +97,19 @@
     
 
 class FilenameDescription(FormatterBase):
-    """substitute the description for the filename"""
+    """
+    obtain the description from the filename
+    the file extension (if any) will be dropped and
+    spaces will be substituted for underscores
+    """
+    # TODO : deal with CamelCaseFilenames
 
     def __call__(self, request, data):
         for f in data['files']:
             if f['description'] is None:
                 description = f['name']
-                description = description.rsplit('.', 1)[0]
+                if '.' in description:
+                    description = description.rsplit('.', 1)[0]
                 decription = description.strip('_')
                 if '_' in description:
                     description = ' '.join([i.title() for i in description.split('_')])
@@ -103,8 +117,15 @@
 
 
 class TitleDescription(FormatterBase):
-    """splits a description into a title and a description with a separator"""
-    
+    """
+    splits a description into a title and a description via a separator in 
+    the description.  The template will now have an additional variable, 
+    'title', per file
+    Arguments:
+    * separator: what separator to use (':' by default)
+    """
+    # XXX what about setting the page title?
+
     defaults = { 'separator': ':' }
         
     def __call__(self, request, data):
@@ -136,7 +157,7 @@
                              for text, link in links ]
 
 class CSS(object):
-    """specify CSS for the page"""
+    """specify CSS used (whitespace separated list)"""
 
     def __init__(self, arg):
         self.css = arg.split()

--- a/decoupage/web.py	Mon Feb 08 11:40:57 2010 -0500
+++ b/decoupage/web.py	Mon Feb 08 11:44:20 2010 -0500
@@ -40,7 +40,9 @@
         self.directory = self.directory.rstrip(os.path.sep)
         assert os.path.isdir(self.directory)
         self.template_directories = self.template_directories.split() # no spaces in directory names, for now
-        assert sum([os.path.isdir(directory) for directory in self.template_directories]) == len(self.template_directories)
+
+        for directory in self.template_directories:
+            assert os.path.isdir(directory), "Decoupage template directory %s does not exist!" % directory
 
         # static file server
         self.fileserver = FileApp