Introduction
------------

The CategoryMenu macro for MoinMoin provides support for navigation menus,
placed in the page content itself, showing the categories present in a Wiki
along with the pages belonging to the selected categories. Categories can be
explicitly selected using macro arguments or implicitly selected using the
category membership of the page on which the macro is used.

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.

To activate the styles provided by the stylesheet in the css directory, you
will need to edit the screen.css file in each affected theme's css directory,
adding the following before any style rules:

  /* Category menus... */

  @import "category.css";

This ensures that the styles are made available to the browser.

Recommended Software
--------------------

The Xapian search software is highly recommended, if not technically
essential, for the acceptable performance of the CategoryMenu macro since the
macro makes use of search routines in MoinMoin that can dominate the time
spent processing requests.

See the following page for information on Xapian and MoinMoin:

http://moinmo.in/HelpOnXapian

Troubleshooting
---------------

See here for a bug related to category recognition:

http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing

This affects installations where migrations between versions have occurred,
yet the Wiki configuration retains old regular expression details.

Contact, Copyright and Licence Information
------------------------------------------

See the following Web page for more information about this work:

http://moinmo.in/MacroMarket/CategoryMenu

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.

New in CategoryMenu 0.2 (Changes since CategoryMenu 0.1)
--------------------------------------------------------

  * Improved category and page discovery, preventing needless inspection of
    all categories, and using the category search method when searching for
    categories.
  * Removed unnecessary page name sorting.
  * Fixed and improved the scripts.
  * Added MoinMoin 1.8.x compatibility.
  * Made displayed page names prettier.
  * Added recommended software and troubleshooting documentation.

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 (see above for the URL).
