==================
 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.