Documentation Tools

While customizing MoinMoin installations for large FAQ sets, I crafted a few macros to address missing functionality. I feel these will benifit others so I have uploaded them to the Macro Market. This page gives examples of how these tools fit together.

There are three primary macros that can help make very large "published" documentation sets. It is sometimes useful to split large documentation sets in to smaller pages. I use these macros to:

• Set predefined section number for a page, rather than starting at 1.
  

  • [[SetSection(section)]]

• Generate TOCs with full section numbers instead of standard lists (1.2.7 instead of just 7.)
  

  • [[EnhancedTableOfContents]]
    This macro also wraps the table of contents with a div with class="tableOfContents" so that it can be formated by CSS.

• Build a master TOC from all the pages (with links to the page and specific section) without using includes
  

  • [[TocOf(page1[,page2[,...]])]]
    This macro also wraps the table of contents with a div with class="tableOfContents" so that it can be formated by CSS.

All of these macros are designed to be used together, but can be used seperately. Unfortunatly, in order to get the desired functionality, I had to use undocumented API and private variables. Because of this, it is only designed to work in MoinMoin 1.5, though anyone is free (and encouraged) to port it to an older or newer version. To download the macros, please go to the MacroMarket.

Example

Here is an example of a large documentation set split in to sections.

LargeManual

This is an example front page for a manual that also doubles as Section One. As you can see below, we turned section-numbers on and used the [[TocOf()]] macro to get the TOC of all the pages, including self.

Source

#pragma section-numbers on
= Large Manual =
This is a test manual for DocTools.

== Table Of Contents ==
[[TocOf(LargeManual,LargeManual/SectionTwo,LargeManual/SectionThree)]]

== One Point Two ==
etc..

Displays

1. Large Manual

This is a test manual for DocTools.
1.1. Table Of Contents

    * 1. Large Manual
          o 1.1. Table Of Contents
          o 1.2. One Point Two

    * 2. Test Section Two
          o 2.1. Test Two Point One
                + 2.1.1. Test Two Point One Point One
          o 2.2. Test Two Point Two

    * 3. Test Section Three
          o 3.1. Test Three One
                + 3.1.1. Test Three One One
          o 3.2. Test Three Two

1.2. One Point Two

etc..

LargeManual/SectionTwo

In this example, you can see that we used the [[SetSection()]] macro to set the starting root section number for the page. You can also see [[TableOfContents]]. On my test server, I have the EnhancedTableOfContents renamed to TableOfContents since it works exactly the same as the original, except when section-numbers are on.

Source

#pragma section-numbers on
[[SetSection(2)]]
= Test Section Two =
This is the second section.
[[TableOfContents]]

== Test Two Point One ==
=== Test Two Point One Point One ===
== Test Two Point Two ==

Displays

2. Test Section Two

This is the second section.

    * 2. Test Section Two
          o 2.1. Test Two Point One
                + 2.1.1. Test Two Point One Point One
          o 2.2. Test Two Point Two

2.1. Test Two Point One
2.1.1. Test Two Point One Point One
2.2. Test Two Point Two

LargeManual/SectionThree

This is a very similar example to Section Two above.

Source

#pragma section-numbers on
[[SetSection(3)]]
= Test Section Three =
[[TableOfContents]]

== Test Three One ==
=== Test Three One One ===
== Test Three Two ==

Displays

3. Test Section Three

    * 3. Test Section Three
          o 3.1. Test Three One
                + 3.1.1. Test Three One One
          o 3.2. Test Three Two

3.1. Test Three One
3.1.1. Test Three One One
3.2. Test Three Two

Credits

I wrote these macros for my job at SQI, Inc.. For the Table of Contents plugins, the code is mostly original MoinMoin code. The changes to the code are Copyright 2006, SQI, Inc. The Set Section macro is Copyright 2006, SQI, Inc. These macros are distributed under the same terms and license as MoinMoin itself and may be integrated within MoinMoin freely.

If there are any questions or suggestions (or if you just like the plugins!), please email me at <steve.tindle AT sqi-inc.com>.