# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1225500152 -3600
# Node ID 6120caa3bfda54b0f670b1fd1c497db133dc4cd5
# Parent  804732b33061db7873b600994e2b5668f4cdfabc
Added documentation and scripts.

diff -r 804732b33061 -r 6120caa3bfda README.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Sat Nov 01 01:42:32 2008 +0100
@@ -0,0 +1,61 @@
+Introduction
+------------
+
+The CategoryMenu macro for MoinMoin provides support for navigation menus,
+placed in the page content itself, showing the categories available in a Wiki,
+along with the pages in the selected category.
+
+Installation
+------------
+
+To install the macro in a Wiki, consider using the instmacros script provided:
+
+  ./instmacros path-to-wiki
+
+On non-UNIX platforms, it is necessary to manually copy the contents of the
+macros directory in this distribution into the macros directory of your Wiki.
+
+It should now be possible to edit pages and use the macro as follows. For
+MoinMoin 1.5:
+
+  [[CategoryMenu()]]
+
+For MoinMoin 1.6 and above:
+
+  <<CategoryMenu()>>
+
+As arguments to the macro, you can indicate a comma-separated list of selected
+(or opened) categories in the menu. For example:
+
+  <<CategoryMenu(Homepage)>>
+
+Although this should display the menu as a hierarchical list, you may wish to
+change the appearance of the menu to something more visually attractive; to do
+so, consider using the insttheme script provided:
+
+  ./insttheme path-to-wiki theme-name
+
+Again, on non-UNIX platforms, it is necessary to manually copy the files. In
+this case, just copy the contents of the css directory into the css directory
+of themes which will support styling of category menus.
+
+Contact, Copyright and Licence Information
+------------------------------------------
+
+No Web page has yet been made available for this work, but the author can be
+contacted at the following e-mail address:
+
+paul@boddie.org.uk
+
+Copyright and licence information can be found in the docs directory - see
+docs/COPYING.txt and docs/LICENCE.txt for more information.
+
+Release Procedures
+------------------
+
+Update the CategoryMenu.py __version__ attribute.
+Change the version number and package filename/directory in the documentation.
+Update the release notes (see above).
+Tag, export.
+Archive, upload.
+Update the MacroMarket (http://moinmo.in/MacroMarket).
diff -r 804732b33061 -r 6120caa3bfda instmacros
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/instmacros	Sat Nov 01 01:42:32 2008 +0100
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+if [ ! $1 ] ; then
+    echo "Please specify a directory such as ../mysite or /tmp/mysite."
+    echo "This should be the root of your Wiki installation and contain the wiki"
+    echo "directory."
+    exit
+fi
+
+cp macros/*.py $1/wiki/data/plugin/macro/
+chown www-data: $1/wiki/data/plugin/macro/*.py
diff -r 804732b33061 -r 6120caa3bfda insttheme
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/insttheme	Sat Nov 01 01:42:32 2008 +0100
@@ -0,0 +1,13 @@
+#!/bin/bash
+
+if [ ! $2 ] ; then
+    echo "Please specify a directory such as ../mywiki or /tmp/mywiki along"
+    echo "with the name of the theme into which the CategoryMenu styles will be"
+    echo "copied."
+    echo "The specified directory should be the root of your Wiki installation"
+    echo "and contain the wiki directory."
+    exit
+fi
+
+cp css/*.css $1/htdocs/$2/css/
+chown www-data: $1/htdocs/$2/css/
diff -r 804732b33061 -r 6120caa3bfda macros/CategoryMenu.py
--- a/macros/CategoryMenu.py	Sat Oct 25 02:09:43 2008 +0200
+++ b/macros/CategoryMenu.py	Sat Nov 01 01:42:32 2008 +0100
@@ -12,9 +12,15 @@
 from MoinMoin import wikiutil, search, version
 import re
 
+__version__ = "0.1"
+
+Dependencies = ['pages']
+
+# Regular expressions where MoinMoin does not provide the required support.
+
 category_regexp = None
 
-Dependencies = ['pages']
+# Utility functions.
 
 def isMoin15():
     return version.release.startswith("1.5.")
@@ -32,6 +38,8 @@
             category_regexp = re.compile(u'^%s$' % ur'(?P<all>Category(?P<key>(?!Template)\S+))', re.UNICODE)
         return category_regexp
 
+# The main activity functions.
+
 def getCategories(request):
 
     """
@@ -81,6 +89,12 @@
     return pages
 
 def execute(macro, args):
+
+    """
+    Execute the 'macro' with the given 'args': an optional list of selected
+    category names (categories whose pages are to be shown).
+    """
+
     request = macro.request
     fmt = macro.formatter
     page = fmt.page
@@ -153,6 +167,8 @@
                     else:
                         break
 
+                # Use an em-dash to indicate subpages.
+
                 prefix = u"\u2014" * common
                 suffix = "/".join(parts[common:])