Revised syntax/method for specifying POIs

docs/signs.rst

@@ -20,32 +20,30 @@ Filter Functions
 ----------------
 
 A filter function is a python function that is used to figure out if a given POI
-should be part of a markerSet of not.  The function should accept one argument
-(a dictionary, also know as an associative array), and return a boolean::
+should be part of a markerSet of not, and to control how it is displayed.  
+The function should accept one argument (a dictionary, also know as an associative
+array), and return a string representing the text to be displayed.  For example::
 
     def signFilter(poi):
-        "All signs"
-        return poi['id'] == 'Sign'
+        if poi['id'] == 'Sign':
+            return "\n".join([poi['Text1'], poi['Text2'], poi['Text3'], poi['Text4']])
+
+If a POI doesn't match, the filter can return None (which is the default if a python 
+functions runs off the end without an explicit 'return').
 
 The single argument will either a TileEntity, or an Entity taken directly from 
-the chunk file.  In this example, this function returns true only if the type
-of entity is a sign.  For more information of TileEntities and Entities, see
+the chunk file.  In this example, this function returns all 4 lines from the sign
+if the entity is a sign.
+For more information of TileEntities and Entities, see
 the `Chunk Format <http://www.minecraftwiki.net/wiki/Chunk_format>`_ page on
 the Minecraft Wiki.
 
-.. note::
-   The doc string ("All signs" in this example) is important.  It is the label
-   that appears in your rendered map
+A more complicated filter function can construct a more customized display text::
 
-A more advanced filter may also look at other entity fields, such as the sign text::
+    def chestFilter(poi):
+        if poi['id'] == "Chest":
+            return "Chest with %d items" % len(poi['Items'])
 
-    def goldFilter(poi):
-        "Gold"
-        return poi['id'] == 'Sign' and (\
-            'gold' in poi['Text1'] or
-            'gold' in poi['Text2'])
-           
-This looks for the word 'gold' in either the first or second line of the signtext.
 
 Since writing these filters can be a little tedious, a set of predefined filters
 functions are provided.  See the :ref:`predefined_filter_functions` section for
@@ -56,15 +54,29 @@ Render Dictionary Key
 
 Each render can specify a list of zero or more filter functions.  Each of these
 filter functions become a selectable item in the 'Signs' drop-down menu in the
-rendered map.  For example::
+rendered map.  Previously, this used to be a list of functions.  Now it is a list
+of dictionaries.  For example::
 
     renders['myrender'] = {
             'world': 'myworld',
             'title': "Example",
-            'markers': [allFilter, anotherFilter],
+            'markers': [dict(name="All signs", filterFunction=signFilter),
+                        dict(name="Chests", filterFunction=chestFilter, icon="chest.png")]
     }
 
 
+The following keys are accepted in the marker dictionary:
+
+``name``
+    This is the text that is displayed in the 'Signs' dropdown.
+
+``filterFunction``
+    This is the filter function.  It must accept at least 1 argument (the POI to filter),
+    and it must return either None or a string.
+
+``icon``
+    Optional.  Specifies the icon to use for POIs in this group.  If omitted, it defaults
+    to a signpost icon.
 
 
 Generating the POI Markers