1 files changed, 33 insertions, 0 deletions
diff --git a/scripts/pandoc.py b/scripts/pandoc.py
index 8bc3afc03..6d7f84b24 100755
--- a/scripts/pandoc.py
+++ b/scripts/pandoc.py
@@ -1,7 +1,19 @@
+# Author: John MacFarlane <jgm@berkeley.edu>
+# Copyright: (C) 2013 John MacFarlane
+# License: GPL version 2 or higher
+
+"""
+Functions to aid writing python scripts that process the pandoc
+AST serialized as JSON.
+"""
+
 import sys
 import json
 
 def walk(x, action, format = ""):
+  """Walk a tree, applying an action to every object.
+  Returns a modified tree.
+  """
   if isinstance(x, list):
     array = []
     for item in x:
@@ -27,6 +39,20 @@ def walk(x, action, format = ""):
     return x
 
 def toJSONFilter(action):
+  """Converts an action into a filter that reads a JSON-formatted
+  pandoc document from stdin, transforms it by walking the tree
+  with the action, and returns a new JSON-formatted pandoc document
+  to stdout.  The argument is a function action(key, value, format),
+  where key is the type of the pandoc object (e.g. 'Str', 'Para'),
+  value is the contents of the object (e.g. a string for 'Str',
+  a list of inline elements for 'Para'), and format is the target
+  output format (which will be taken for the first command line
+  argument if present).  If the function returns None, the object
+  to which it applies will remain unchanged.  If it returns an
+  object, the object will be replaced.  If it returns a list, the
+  list will be spliced in to the list to which the target object
+  belongs.  (So, returning an empty list deletes the object.)
+  """
   doc = json.loads(sys.stdin.read())
   if len(sys.argv) > 1:
     format = sys.argv[1]
@@ -36,12 +62,19 @@ def toJSONFilter(action):
   json.dump(altered, sys.stdout)
 
 def rawInline(format, s):
+  """Returns a 'RawInline' inline object.
+  """
   return {"RawInline": [{"unFormat": format}, s]}
 
 def rawBlock(format, s):
+  """Returns a 'RawBlock' inline object.
+  """
   return {"RawBlock": [{"unFormat": format}, s]}
 
 def attributes(attrs):
+  """Returns an attribute list, constructed from the
+  dictionary attrs.
+  """
   attrs = attrs or []
   ident = attrs["id"] or ""
   classes = attrs["classes"] or []