## page was renamed from HelpOnFslDocs
## page was renamed from HelpOnFSLDocumentation
<<TableOfContents>>
= 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
}}}

{{{#!wiki note
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'''<<BR>> 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 [[HelpOnParsers#highlight_parser|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

{{{#!highlight console
cd $HOME
ls -l
}}}
or for Python code:

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

{{{#!highlight python
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:

 1. Visit the URL ''SITE''/CategoryScripting (in the case of the FSLdev Wiki, `https://fsl.fmrib.ox.ac.uk/fsl/fsldev/CategoryScripting`).
 1. When offered, choose to create a page using the !CategoryTemplate
 1. Modify this template, changing the ''Describe the pages in this category...'' part to reflect your new category.
 1. 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 <<MailTo(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
...
}}}
}}}}