Commented python modules/sample scripts.

5 files changed, 59 insertions, 7 deletions

diff --git a/scripts/caps.py b/scripts/caps.py
index 3ab8bc7a3..e29d48854 100755
--- a/scripts/caps.py
+++ b/scripts/caps.py
@@ -1,4 +1,9 @@
 #!/usr/bin/env python
+
+"""Pandoc filter to convert all regular text to uppercase.
+Code, link URLs, etc. are not affected.
+"""
+
 from pandoc import toJSONFilter
 
 def caps(key, value, format):
diff --git a/scripts/comments.py b/scripts/comments.py
index 3767f973a..5700c3485 100755
--- a/scripts/comments.py
+++ b/scripts/comments.py
@@ -2,9 +2,16 @@
 from pandoc import toJSONFilter
 import re
 
+"""Pandoc filter that causes everything between
+'<!-- BEGIN COMMENT -->' and '<!-- END COMMENT -->'
+to be ignored.  The comment lines must appear on
+lines by themselves, with blank lines surrounding
+them.
+"""
+
 incomment = False
 
-def comment(k,v,format=""):
+def comment(k,v,fmt):
   global incomment
   if k == 'RawBlock':
     f, s = v
diff --git a/scripts/deemph.py b/scripts/deemph.py
index c1d532969..467641b4a 100755
--- a/scripts/deemph.py
+++ b/scripts/deemph.py
@@ -2,9 +2,13 @@
 from pandoc import walk, toJSONFilter
 from caps import caps
 
-def deemph(k,v,f):
-  if k == 'Emph' and f == 'html':
-    return walk(v,caps,f)
+"""Pandoc filter that causes emphasized text to be displayed
+in ALL CAPS.
+"""
+
+def deemph(key, val, fmt):
+  if key == 'Emph':
+    return walk(val, caps, fmt)
 
 if __name__ == "__main__":
   toJSONFilter(deemph)
diff --git a/scripts/myemph.py b/scripts/myemph.py
index 92f6202b4..0514df317 100755
--- a/scripts/myemph.py
+++ b/scripts/myemph.py
@@ -1,11 +1,14 @@
 #!/usr/bin/env python
 from pandoc import toJSONFilter, rawInline
 
+"""Pandoc filter that causes emphasis to be rendered using
+the custom macro '\myemph{...}' rather than '\emph{...}'
+in latex.  Other output formats are unaffected.
+"""
+
 def myemph(k, v, f):
   if k == 'Emph' and f == 'latex':
-    v.insert(0, rawInline("latex", "\\myemph{"))
-    v.append(rawInline("latex", "}"))
-    return v
+    return [rawInline("latex", "\\myemph{")] + v + [rawInline("latex","}")]
 
 if __name__ == "__main__":
   toJSONFilter(myemph)
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 []