From e2b24a7a0f2bdd690bf651b36dd554454d7a3146 Mon Sep 17 00:00:00 2001
From: stoneLeaf <owi.stoneleaf@gmail.com>
Date: Tue, 10 Apr 2012 18:07:44 +0300
Subject: [PATCH] Added a new section entitled 'A dynamic config file'. It
 explains the use of environment variables in the config file to dynamically
 retrieve parameters.

---
 docs/config.rst | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/docs/config.rst b/docs/config.rst
index dac2c12..e256843 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -115,6 +115,53 @@ individual renders to apply to just those renders.
     See the ``sample_config.py`` file included in the repository for another
     example.
 
+A dynamic config file
+=====================
+
+It might be handy to dynamically retrieve parameters. For instance, if you
+periodically render your last map backup which is located in a timestamped
+directory, it is not convenient to edit the config file each time to fit the
+new directory name.
+
+Using environment variables, you can easily retrieve a parameter which has
+been set by, for instance, your map backup script. In this example, Overviewer is
+called from a *bash* script, but it can be done from other shell scripts and
+languages.
+
+::
+
+    ## The bash script
+    
+    # Setting up an environment variable that child processes will inherit
+    MYWORLD_DIR=/path/to/map/backup/$yourtimestamp/YourWorld
+    export MYWORLD_DIR
+    
+    # Running the Overviwer
+    overviewer.py --config=/path/to/yourConfig.py
+
+.. note::
+
+    The environment variable will only be local to the process and its child
+    processes. In this example, the Overviewer will be able to access the 
+    variable since it becomes a child process.
+
+::
+
+    ## The config file
+    
+    # Importing the os python module
+    import os
+    
+    # Retrieving the environment variable
+    worlds["My world"] = os.environ['MYWORLD_DIR']
+
+    renders["normalrender"] = {
+        "world": "My world",
+        "title": "Normal Render of My World",
+    }
+
+    outputdir = "/home/username/mcmap"
+
 Config File Specifications
 ==========================