Contributions

Contributing to the Wiki

The wiki software hosting this set of documentation may not be entirely familiar to everyone. It is based around Gollum, a GitHub specific wiki-esque platform that supports a variety of different markup languages, and stores history in a git repository backend.

File Types

There are two major file types used here:

• POD

• Markdown

Most of the actual documentation is in `.pod` format, whilst the various ancillary pages are written in markdown.

Linking Issues with POD

Currently, the POD renderer for Gollum has some issues with resolving link (L<...>) tags. As such, they should only be used for internal (within a single page, to a specific anchor name) links and External links. Links to other wiki pages have to use the [[name|location]] format. Linking to a specific section within a POD page can be achieved with [[name|location#wiki-SECTION_NAME]] (manually check the anchor in the source code, observe the wiki- prefix...)

Header Auto-generation

Gollum currently supports automatic page footers (via the _footer page), but does not have a way to specify headers, or table-of-contents. This is currently being worked around by the use of a script (tools/make_header.pl, and the template file tools/_header.tt) This script is responsible for generating "breadcrumb" style navigation links at the top of the page, and also a rudimentary table of contents.

I haven't yet found a way to run this automatically, so it may require a manual rebuild from time to time.

Note: In order for the header insertion script to work, each POD file must contain (after the initial =head1 $title section), the following content:

  X<begin header>
  X<end header>

The space between these markers will be filled with the header contents following the execution of the make_header.pl script.