1 Introduction
2 ------------
3
4 The CategoryMenu macro for MoinMoin provides support for navigation menus,
5 placed in the page content itself, showing the categories present in a Wiki
6 along with the pages belonging to the selected categories. Categories can be
7 explicitly selected using macro arguments or implicitly selected using the
8 category membership of the page on which the macro is used.
9
10 Installation
11 ------------
12
13 To install the macro in a Wiki, consider using the instmacros script provided:
14
15 ./instmacros path-to-wiki
16
17 On non-UNIX platforms, it is necessary to manually copy the contents of the
18 macros directory in this distribution into the macros directory of your Wiki.
19
20 It should now be possible to edit pages and use the macro as follows. For
21 MoinMoin 1.5:
22
23 [[CategoryMenu()]]
24
25 For MoinMoin 1.6 and above:
26
27 <<CategoryMenu()>>
28
29 As arguments to the macro, you can indicate a comma-separated list of selected
30 (or opened) categories in the menu. For example:
31
32 <<CategoryMenu(Homepage)>>
33
34 Although this should display the menu as a hierarchical list, you may wish to
35 change the appearance of the menu to something more visually attractive; to do
36 so, consider using the insttheme script provided:
37
38 ./insttheme path-to-wiki theme-name
39
40 Again, on non-UNIX platforms, it is necessary to manually copy the files. In
41 this case, just copy the contents of the css directory into the css directory
42 of themes which will support styling of category menus.
43
44 To activate the styles provided by the stylesheet in the css directory, you
45 will need to edit the screen.css file in each affected theme's css directory,
46 adding the following before any style rules:
47
48 /* Category menus... */
49
50 @import "category.css";
51
52 This ensures that the styles are made available to the browser.
53
54 Recommended Software
55 --------------------
56
57 The Xapian search software is highly recommended, if not technically
58 essential, for the acceptable performance of the CategoryMenu macro since the
59 macro makes use of search routines in MoinMoin that can dominate the time
60 spent processing requests.
61
62 See the following page for information on Xapian and MoinMoin:
63
64 http://moinmo.in/HelpOnXapian
65
66 Troubleshooting
67 ---------------
68
69 See here for a bug related to category recognition:
70
71 http://moinmo.in/MoinMoinBugs/1.7TemplatesNotAppearing
72
73 This affects installations where migrations between versions have occurred,
74 yet the Wiki configuration retains old regular expression details.
75
76 Contact, Copyright and Licence Information
77 ------------------------------------------
78
79 See the following Web page for more information about this work:
80
81 http://moinmo.in/MacroMarket/CategoryMenu
82
83 The author can be contacted at the following e-mail address:
84
85 paul@boddie.org.uk
86
87 Copyright and licence information can be found in the docs directory - see
88 docs/COPYING.txt and docs/LICENCE.txt for more information.
89
90 New in CategoryMenu 0.3 (Changes since CategoryMenu 0.2)
91 --------------------------------------------------------
92
93 * Restored MoinMoin 1.5.x compatibility.
94 * Changed the presentation of subpages in the menu, using » instead of an
95 em-dash.
96
97 New in CategoryMenu 0.2 (Changes since CategoryMenu 0.1)
98 --------------------------------------------------------
99
100 * Improved category and page discovery, preventing needless inspection of
101 all categories, and using the category search method when searching for
102 categories.
103 * Removed unnecessary page name sorting.
104 * Fixed and improved the scripts.
105 * Added MoinMoin 1.8.x compatibility.
106 * Made displayed page names prettier.
107 * Added recommended software and troubleshooting documentation.
108
109 Release Procedures
110 ------------------
111
112 Update the CategoryMenu.py __version__ attribute.
113 Change the version number and package filename/directory in the documentation.
114 Update the release notes (see above).
115 Tag, export.
116 Archive, upload.
117 Update the MacroMarket (see above for the URL).