improve doc of get_filename4code and better backward compatible behavior

See #88

README.rst

@@ -222,15 +222,16 @@ for developing your own pandocfilters.
     package is available. Also assumes that ImageMagick's convert is in
     the path. Images are put in the ``tikz-images`` directory.
 
-Cleanup after run
+API documentation
 -----------------
 
-By default most filters create a directory ``...-images`` to save temporary
+By default most filters use ``get_filename4code`` to
+create a directory ``...-images`` to save temporary
 files. This directory doesn't get removed as it can be used as a cache so that
 later pandoc runs don't have to recreate files if they already exist. The
 directory is generated in the current directory.
 
-If you prefer to have a clean directory after the run of the pandoc filter, you
-can set an environment variable ``PANDOCFILTER_CLEANUP`` to the value ``true``
-which forces the code to create a real temporary directory that will be removed
-after the filter has finished.
+If you prefer to have a clean directory after running pandoc filters, you
+can set an environment variable ``PANDOCFILTER_CLEANUP`` to any non-empty value such as `1`
+which forces the code to create a temporary directory that will be removed
+by the end of execution.

pandocfilters.py

@@ -25,31 +25,34 @@ def get_filename4code(module, content, ext=None):
     """Generate filename based on content
 
     The function ensures that the (temporary) directory exists, so that the
-    file can be written. In the usual case the directory doesn't get removed
-    afterwards, so a plugin can use the directory for caching purposes and
-    decide not to recreate an already existing file.
+    file can be written.
 
-    In case the user preferres the files to be actual temporary files, he can
-    set an environment variable `PANDOCFILTER_CLEANUP` to the value `true` to
+    By default, the directory won't be cleaned up,
+    so a filter can use the directory as a cache and
+    decide not to regenerate if there's no change.
+
+    In case the user preferres the files to be temporary files,
+    an environment variable `PANDOCFILTER_CLEANUP` can be set to
+    any non-empty value such as `1` to
     make sure the directory is created in a temporary location and removed
-    after finishing the filter.  In this case no caching whatsoever can be
-    done.
+    after finishing the filter. In this case there's no caching and files
+    will be regenerated each time the filter is run.
 
     Example:
         filename = get_filename4code("myfilter", code)
     """
-    if os.getenv('PANDOCFILTER_CLEANUP') == 'true':
+    if os.getenv('PANDOCFILTER_CLEANUP'):
         imagedir = tempfile.mkdtemp(prefix=module)
         atexit.register(lambda: shutil.rmtree(imagedir))
     else:
         imagedir = module + "-images"
-        try:
-            os.mkdir(imagedir)
-            sys.stderr.write('Created directory "' + imagedir + '"\n')
-        except OSError:
-            sys.stderr.write('Could not create directory "' + imagedir + '"\n')
-            raise
     fn = hashlib.sha1(content.encode(sys.getfilesystemencoding())).hexdigest()
+    try:
+        os.mkdir(imagedir)
+        sys.stderr.write('Created directory ' + imagedir + '\n')
+    except OSError:
+        sys.stderr.write('Could not create directory "' + imagedir + '"\n')
+        pass
     if ext:
         fn += "." + ext
     return os.path.join(imagedir, fn)