Author: Nir Soffer <nirs@freeshell.org>

# Sections Parsers

## Design rich pages in a maintainable way

Author: | Nir Soffer <nirs@freeshell.org>
Version: | 1.0
MoinMoin: | Release 1.3.4
License: | GPL

# Install

> 1. Copy parsers in plugin/parsers into your wiki/data/plugin/parser directory. section.py is required by other section plugins.
> 2. Copy MoinMoin/util/header.py into your MoinMoin/util directory.
> 3. Add the content of theme/sections.css to your theme screen.css.

# Section Parser

Use a section if sidebar and figure do not fit. To add a section, add this markup:

    {{{
    #!section
    Text...
    }}}

To design section, add rules in your screen.css:

    #content .section {...}

## Processing Instructions

A section may have processing instructions, just like a page:

#class value
  will be added to the base class, e.g class="section value"
#format value
  will use value parser to format the section (default 'wiki')
#language value
  will add lang="value" and dir="rtl|ltr" to the section div.

# Sidebar Parser

Use a sidebar to put related page links, meta data, and other stuff that need quick access on a side bar in the page itself:

    {{{
    #!sidebar
    === What's this wiki about? ===
     * This
     * And this...
    ## More stuff as needed...
    }}}

The sidebar is designed using the #content .sidebar styles. It will float to the end of the page, on the right side on left to right pages, and on the left side on right to left pages.

# Figure Parser

Use a figure to add pictures, graphs or any data you want to float in the page with the page text following around it. Add the source on the first paragraph, and the title on the second paragraph. Figure text is always bold and centered. To add a figure, add this markup:

    {{{
    #!figure
    http://example.com/example.png

    ## This will be the title
    A fine example from example.com.
    }}}

The figure is designed using the #content .figure styles. It will float to the end of the page - right on left to right languages and left on right to left languages.

## Figure classes

Use right of left classes to have the figure float to specific side:

    {{{
    #!figure
    #class left
    I will float to the left
    }}}

    {{{
    #!figure
    #class right
    I will float to the right
    }}}

# Known Problems

> - #section-number on will show numbers in the sidebar headings, which might look wrong.
> - You can't nest preformatted section inside a section due to limits of the wiki parser. To workaround this, you must use `[[Include()]]` macro.

# Creating New Section Plugin

You many want to create new section plugin, so you can use markup like this:

    {{{
    #!abstract
    }}}

Instead of:

    {{{
    #!section
    #class abstract
    }}}

To create new plugin, create a file named abstract.py in your wiki/data/plugin/parser, and use this little code:

    from section import SectionParser
    class Parser(SectionParser):
        baseClass = 'abstract'

And add css rule to screen.css:

    #content .abstract {text-align: center; font-weight: bold;}

Note:
  You should not create section with exiting parsers names, like wiki or python. Look into MoinMoin/parser to see which names are already used.