Merge remote branch 'source/master' into remote-tiles

Conflicts:
	overviewer.py

docs/config.rst

@@ -552,6 +552,18 @@ values. The valid configuration keys are listed below.
 
     **Default:** ``[]`` (an empty list)
 
+.. _option_overlay:
+
+``overlay``
+    This specifies which renders that this render will be displayed on top of. 
+    It should be a list of renders.
+
+    .. warning::
+
+       At this time, this feature is not fully implemented.
+
+    **Default:** ``[]`` (an empty list)
+
 ``showspawn``
     This is a boolean, and defaults to ``True``. If set to ``False``, then the spawn
     icon will not be displayed on the rendered map.
@@ -636,6 +648,15 @@ Cave
     only_lit
         Only render lit caves. Default: False
 
+Hide
+    Hide blocks based on blockid. Blocks hidden in this way will be
+    treated exactly the same as air.
+
+    **Options**
+
+    minerals
+        A list of block ids, or (blockid, data) tuples to hide.
+
 DepthTinting
     Tint blocks a color according to their depth (height) from bedrock. Useful
     mainly for cave renders.

docs/signs.rst

@@ -20,51 +20,97 @@ 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.  It could also be a special entity representing a player's location
+or a player's spawn.  See below for more details.
+
+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
 details.
 
+
+Special POIs
+------------
+
+There are currently two special types of POIs.  They each have a special id:
+
+PlayerSpawn
+  Used to indicate the spawn location of a player.  The player's name is set
+  in the ``EntityId`` key, and the location is in the x,y,z keys
+
+Player
+  Used to indicate the last known location of a player.  The player's name is set
+  in the ``EntityId`` key, and the location is in the x,y,z keys.
+
+.. note::
+  The player location is taken from level.dat (in the case of a single-player world) 
+  or the player.dat files (in the case of a multi-player server).  The locations are 
+  only written to these files when the world is saved, so this won't give you real-time
+  player location information. 
+
+Here's an example that displays icons for each player::
+
+    def playerIcons(poi):
+        if poi['id'] == 'Player':
+            poi['icon'] = "http://overviewer.org/avatar/%s" % poi['EntityId']
+            return "Last known location for %s" % poi['EntityId']
+
+Note how each POI can get a different icon by setting ``poi['icon']``
+
 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.  Note that each POI can have different icon by setting the key 'icon'
+    on the POI itself (this can be done by modifying the POI in the filter function.  See the
+    example above)
 
 
 Generating the POI Markers