bumped docs to 0.4. Also lots of docs changes

Added faq entry about exorbitant memory usage

updated features section on the main page

Added a "what overviewer is not" section on main page

put new rendermodes on the options page

re-worded some things under the custom rendermodes section

docs/conf.py

@@ -48,9 +48,9 @@ copyright = u'2010-2011 the Overviewer Team'
 # built documents.
 #
 # The short X.Y version.
-version = "0.3"
+version = "0.4"
 # The full version, including alpha/beta/rc tags.
-release = "0.3.0"
+release = "0.4"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/faq.rst

@@ -84,3 +84,20 @@ command lines, but information on how to do this has also not been written.
 
 On a related note, we also welcome contributions for a graphical interface for
 the Overviewer.
+
+The Overviewer is eating up all my memory!
+------------------------------------------
+
+We have written The Overviewer with memory efficiency in mind. On even the
+largest worlds we have at our disposal to test with, it should not be taking
+more than a gigabyte or two. It varies of course, that number is only an
+estimate, but most computers with a reasonable amount of RAM should run just
+fine.
+
+If you are seeing exorbitant memory usage, then it is likely either a bug or a
+subtly corrupted world. Please file an issue or come talk to us on IRC so we can
+take a look. See :ref:`help`.
+
+We have had a few reports of The Overviewer eating all a system's RAM but we
+have been unable to figure out why or duplicate the issue. Any help or evidence
+you can provide us will help us figure this out!

docs/index.rst

@@ -28,22 +28,55 @@ examples, see `The Example Wiki Page <https://github.com/overviewer/Minecraft-Ov
 Features
 ========
 
-* Renders large resolution images of your world, such that you can zoom in and
-  see details
+* Renders high resolution images of your world, let's you "deep zoom" and see
+  details!
+
+* Gloriously awesome smooth lighting is here! (use
+  :option:`--rendermodes=smooth-lighting <--rendermodes>`)
 
 * Customizable textures! Pulls textures straight from your installed texture
   pack!
 
-* Outputs a Google Map powered interface that is memory efficient, both in
-  generating and viewing.
+* Generates a Google Maps powered map!
+
+* Runs on Linux, Windows, and Mac platforms!
 
 * Renders efficiently in parallel, using as many simultaneous processes as you
   want!
 
-* Utilizes caching to speed up subsequent renderings of your world.
+* *Only* requires: Python, Numpy, and PIL (all of which are included in the
+  Windows download!)
+
+* Utilizes caching to speed up subsequent renderings of your world. Only parts
+  that need re-rendering are re-rendered.
 
 * Throw the output directory up on a web server to share your Minecraft world
-  with everyone!
+  with the internet!
+
+* Run The Overviewer from a command line or on a cron schedule for constantly
+  updated maps! Run it for your Minecraft server world to provide your users
+  with a detailed map!
+
+What The Overviewer is not
+--------------------------
+Full disclosure disclaimers of what The Overviewer is *not*.
+
+* It does not run fast. Because of the high level of detail, initial renders of
+  a world can take some time. Expect minutes for medium worlds, hours for large
+  to huge worlds. Subsequent renders are *much* faster due to the caching.
+
+  Also note that speed is improving all the time. We continually make efficiency
+  improvements to The Overviewer. Besides, for the level of detail provided,
+  our users consider it worth the time!
+
+* Overviewer is not targeted at end users. We mainly see Overviewer fitting in
+  best with server operators, rendering their server's map for all users to
+  view.
+
+  You are welcome to use Overviewer for your single player worlds, and it will
+  work just fine. However, since the only interface is currently command line
+  based, you will need to know a bit about the command line in order to operate
+  The Overviewer.
 
 Requirements
 ============
@@ -79,6 +112,7 @@ bad)**, head to the :doc:`Building <building>` page.
 **For all other platforms** you will need to build it yourself.
 :doc:`building`.
 
+.. _help:
 
 Help
 ====

docs/options.rst

@@ -106,11 +106,25 @@ Useful Options
     Powershell on Windows), you can also use a colon ':' or a forward slash '/'
     to separate the modes.
 
-    Incomplete list of common render-modes for your convenience:
+    **More information is available in the** :ref:`render-modes` **section of the
+    docs**
+
+    List of built-in render-modes:
     
     * normal
     * lighting
+    * smooth-lighting
+    * smooth-night
     * night
+    * cave
+
+    Built-in overlays:
+      * spawn
+      * mineral
+
+    .. note::
+        You can create custom rendermodes too! See the :ref:`custom-rendermodes`
+        section for more information!
 
     Example::
     
@@ -123,8 +137,6 @@ Useful Options
 
         Default: only render the normal mode
 
-    See the `Render Modes`_ section for more information.
-
 .. cmdoption:: --list-rendermodes
 
     List the available render modes, and a short description of each, and exit.
@@ -479,6 +491,8 @@ Less Useful Options
     There are **more settings** that cannot be specified on the command line.
     See the section below!
 
+.. _settings-file:
+
 Settings File
 =============
 
@@ -539,6 +553,8 @@ In addition to the `Command line options`_, you can specify these options.
 
     See the `Defining Custom Rendermodes`_ section for more information.
 
+.. _render-modes:
+
 Render Modes
 ============
 
@@ -574,6 +590,9 @@ relationships. Right now, it looks something like this:
 
   * lighting
 
+    * smooth-lighting
+
+      * smooth-night
     * night
     * cave
 
@@ -651,14 +670,22 @@ color.
 
 See the *settings.py* example below for an example usage of **minerals**.
 
+.. _custom-rendermodes:
+
 Defining Custom Rendermodes
 ---------------------------
+Custom rendermodes allow you to take an existing rendermode, and define a new
+one with a particular set of options. You can, for example, render two map
+layers with the same mode, but with two different sets of options. You can do
+this by defining a custom rendermode in your :ref:`settings-file`
 
-Sometimes, you want to render two map layers with the same mode, but with two
-different sets of options. For example, you way want to render a cave mode with
-depth tinting, and another cave mode with lighting and no depth tinting. In this
-case, you will want to define a 'custom' render mode that inherits from 'cave'
-and uses the options you want. For example::
+.. note::
+    You *must* use a :ref:`settings file <settings-file>` in order to define custom rendermodes.
+
+Let's say you want to render a cave mode with depth tinting, and another cave
+mode with lighting and no depth tinting. In this case, you can to define a
+custom render mode that inherits from 'cave' and uses the options you want. Like
+this::
 
     custom_rendermodes = {
         'cave-lighting': {
@@ -674,6 +701,8 @@ and uses the options you want. For example::
 
     rendermode = ['cave', 'cave-lighting']
 
+These lines would go in your settings file as written.
+
 Each entry in ``custom_rendermodes`` starts with the mode name, and is followed
 by a dictionary of mode information, such as the parent mode and description
 (for your reference), a label for use on the map, as well as the options to