Page templates

We have included several templates to help with the creation of the documentation. So far the templates included are:

FslToolTemplate	For creating your top-level tool page, see below for how to layout your documentation
FslToolSubpageTemplate	For creating sub-pages for your tool
FslFaqTemplate	For creating FAQs
CategoryTemplate	Built-in For creating a new category to appear in the `Add to` menu

To use a template, visit a non-existant page and choose from the left-hand column of the table displayed on the page creation page.

Layout of documentation - using sub-pages

We recommend that all tools have a top-level page called TOOLNAME which contains two sections, an introduction and a list of references for this tool, eg for TBSS:

Pagename - TBSS

Section 1 - Tract-Based Spatial Statistics

Contains a summary of the tools purpose

Section 2 - Referencing

Contains the referencing details. Your references should be in a block delimited with:

{{{#!wiki references
...
}}}

which will automatically indent and italicise the text. To un-italicise a section use the italics Wiki markup.

Then create sub-pages to contain the remainder of the content. Sub-pages are named TOOLNAME/SUBPAGE, eg TBSS/Faq. The required minimum pages are:

UserGuide
Faq
FurtherInformation

although your tool may require additional sections.

FurtherInformation should contain the sections:

Theory
Background information
Related web links
Future work

Providing a contents menu

At the start of each tool page you should include a contents list, we have provided a macro which will automate this process FslToolContents. To prepare for it's use you must first create a contents list page for your tool, do this by creating a new page TOOLNAME/Contents containing the sub-page names, in the order you wish them to appear, one per line. Do not include any mark-up, comments etc, and do not include the TOOLNAME or Introduction in the list. eg:

```
 UserGuide
 Faq
 FurtherInformation
```

Now on each sub-page (and the TOOLNAME page) include, at the start of the page

```
 <<FslToolContents>>
```

The macro automatically adds the link back to the TOOLNAME page (displayed as Introduction), adds a space to Wikiwords to aid readability and capitalises Faq. For the current page, no link is setup and a contents list is displayed for this section, generated from the headings (and sub-headings) of the page. Where one of the specified sub-pages doesn't exist, it won't appear in the contents list. For example, the above contents page would result in:

Contents
  1. Introduction
   1.1. Tract-Based Spatial Statistics
   1.2. Referencing
  2. User Guide
  3. FAQ
  4. Further Information

The contents list will only be displayed when these sub-pages actually exist on the system. This allows you to setup the documentation for your tool and gradually add sections without the contents page containing broken links. If you have a single page and want a table of contents then use the built in <<TableOfContents>> macro instead.

Automated FSL list searching

FslSearchJiscMail
This macro can be called to create a link on the page which will add a form allowing you to search the FSL mailing list for the specified text, eg:

 <<FslSearchJiscMail('TBSS')>>

will give a search form which will search for TBSS AND whatever the user enters into the text field.

To search for only what the user specifies, call with no options:

 <<FslSearchJiscMail>>

Things to use/avoid

MoinMoin provides lots of mark up options for you to make your pages look nice. Read HelpOnMoinWikiSyntax for a full description of all the available options. I would strongly encourage you to use the highlight function when you are including source code/scripts in your page. For example, if you are documenting commands that should be entered into a BASH session highlight this with

{{{#!highlight console
cd $HOME
ls -l
}}}

which gives

   1 cd $HOME
   2 ls -l
   3

or for Python code:

{{{#!highlight python
import matplotlib
}}}

to give

   1 import matplotlib

If you don't want line numbers, add numbers=disable to the highlight control line.

Categories

MoinMoin supports the concept of page categories. By tagging your pages with one or more categories you can use macros to search for pages in a category. We use this to automatically add your tool pages to the main menu of FSL tools. To specify the categories for your page, use the Add to: drop-down menu at the bottom of the page editor to select the categories. They are then appended to the page as the last line of the document, where they must stay for the search functions to work. Secondary categories can be added with the same menu, appearing in double square brackets, eg:

CategoryDiffusion [[CategoryTBSS]]

would add your page to the Diffusion tools category and the TBSS category. If you wish to create a new category, for example CategoryScripting follow these steps:

Visit the URL SITE/CategoryScripting (in the case of the FSLdev Wiki, https://fsl.fmrib.ox.ac.uk/fsl/fsldev/CategoryScripting).
When offered, choose to create a page using the CategoryTemplate
Modify this template, changing the Describe the pages in this category... part to reflect your new category.
Save the category.

This will then appear in the Add to: drop-down.

To add a search for pages with a category, add the following macro to your page:

<<FullSearch(category:CategoryFunctional)>>

Custom styles

The FSL theme has the following additional styles defined:

centred This style will centre the item to which it has been applied. This is most useful for tables; to centre a table use:
```
 ||<tableclass='centred'>Cell1||Cell2||
```
references This can only be applied to a section of text, see above for usage

If you need a specific style then please email me <duncan AT fmrib DOT ox DOT ac DOT uk> to ask about creating it. You can then use the defined style with the following:

{{{#!wiki mystylename
...
}}}