The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Konstrukt-0.5-beta13
River stage zero No dependents
++
/ Konstrukt::Plugin::wiki::syntax

NAME

Konstrukt::Plugin::wiki::syntax - Overview of the Syntax of the wiki plugin. For more details, take a look at the documentation of each markup plugin.

BLOCK SYNTAX

definition

This one will match if the first line of the block start with a semicolon ";" followed by at least one whitespace or tab.

Multiple definition terms (indicated by a ";" at the beginning of the line) per list and multiple definitions per term (indicated by a ":" at the beginning of the line) are possible.

This plugin has some similarities with Konstrukt::Plugin::wiki::markup::list.

Example:

        ; definition term
        : first definition
        : second definition
        ; another definition term
        : first definition
        : second definition

headline

This one will match if the first character of the first line of the block is a =.

The block will then be enclosed by <hX> and </hX> (X = number of ='s before the first character).

Any trailing ='s at the end of the block will be removed.

Example:

        = headline of level 1
        
        some text
        
        == headline of level 2
        
        some other text

hr

This one will match if the block consists of only one line that just contains dashes (-).

The block will be replaced by a <hr>-tag.

Example:

        those two paragraphs
        
        ------
        
        will be separated by a horizontal rule

list

This one will match if the first character of the first line of the block is a * (-> unordered list) or # (->ordered list).

The block will then be enclosed by <ul> and </ul> or <ol> and </ol>. Each line with leading bullets will be added as a list item. Deeper levels in the list can be achieved by putting more than one bullet in from of the line.

Example:

        * this
        ** is
        *** an
        ** unordered
        * list
        
        # this
        ## one
        ### will
        ## be
        # ordered

paragraph

This one won't do much more but putting <p> and </p> around a block.

It matches all blocks and should be the last plugin in your filter chain so it will catch all block that didn't match any other plugin.

Example:

        this is
        one paragraph and will be surrounded
        by <p> and </p>
        
        this one also

pre

This one will match if the first character of the first line of the block is a whitespace or a tab.

The block will then be enclosed by <pre> and </pre>. All child nodes will be tagged as finished to prevent further wiki parsing on them.

Example:

         although only the first line is indented
        the whole block will be marked as code.

quote

This one will match if the first line of the block start with a colon ":" followed by at least one whitespace or tab.

The block will then be surrounded by <blockquote> and </blockquote> tags.

Example:

        : 640kb should be enough for everyone.
        
        : God does not play dice
        - Albert Einstein

INLINE SYNTAX

acronym

This one will look for acronyms with an explanation and replace it:

        IP(Internet Protocol) => <span title="Internet Protocol">IP</span>

Actually it will work for every "word" that does not contain spaces and is followed by some text in parenthesis.

Example:

        TCP(Transmission Control Protocol)/IP(Internet Protocol)
        
        Foo-Bar(baz)

basic

This one will handle all basic text formatting markup and substitute it with html-markup.

Example:

        *strong*
        _strong2_
        /empathized/
        -deleted-
        +inserted+
        ^superscript^
        ~subscript~
        `code`

htmlescape

This one will do a simple search and replace for a some critical characters (i.e. <, >, & and ") and will replace them.

The replacement will only be done on text nodes, that are not wiki_finished.

You might want to put this one as late as possible in the filter chain.

Example:

        This <html> will be escaped.
        
        <nowiki><em>This</em> HTML won't be escaped.</nowiki>

This one will look for (internal and external, implicit and explicit) links and converts them into HTML-links.

Example:

Implicit links

        CamelCase or SomePage
        
        http://foo.bar/baz
        
        !NoLink

Explicit links

        Explicit links are required here [[nocamelcase]] or here [[NoSpaceAroundLink]].
        
        [[SomePage|But with some other description]]
        
        [[http://foo.bar/baz|somthing here]]

link::article

This one will be responsible for all wiki links (CamelCase, [[nocamelcase]]).

You should put this one at the end of the list of the link plugins since it will act like a 'catch all' plugin to match all links that haven't been matched by another plugin.

Example:

Implicit links

        CamelCaseLink
        
        !ThisLinkWontMatch

Explicit links (with description)

        [[thislinkwillmatch]]

        [[CamelCaseLink|but with another description]]
        
        [[linikwith#anchor]]

link::external

This one will be responsible for all external links (http://, ftp://, mailto:, news:, ...). The links will be surrounded by <a> and </a>.

Example:

Implicit links

        http://foo.bar/baz

Explicit links (with description)

        [[http://foo.bar/baz]]

        [[http://foo.bar/baz|something here]]

link::file

This one will be responsible for all internal files.

A link to the file will be created. If the target file doesn't exist, the user may upload it.

Note that the filename will be normalized. All characters but letters, numbers, parenthesis and dots will be replaced by underscores.

Example:

Implicit

        file:somefile.zip

Explicit

        [[file:some other file.rar|with a different link text]]

link::image

This one will be responsible for all internal and external image links.

Internal images will be displayed on the page with a default width of 180px. They will link to a page with the full sized image.

External images will just be linked and not displayed unless you define a parameter to show them.

Note that the filename of internal images will be normalized. All characters but letters, numbers, parenthesis and dots will be replaced by underscores.

Example:

Internal images

        inline image: image:foo.jpg
        explicit image with alternative text: [[image:foo bar baz|alternative text (default = image name)]]
        explicit image with specified width: [[image:foo|200px]]
        
        Parameter reference:
        left: align the image on the left side
        right: align the image on the right side
        center: centered alignment of the image
        123px: width in pixels
        thumb: alias for 100px width
        text at the end: caption text (also alt-text)
        
        Default alignment: No special alignment, but may be overridden by the
        template/stylesheet.

External images (.gif, .jpg, .png)

        implicit image: http://foo.bar/baz.gif
        explicit image: [[http://foo.bar/baz bar foo.jpg|link text]]
        explicit image displayed on the page: [[http://foo.bar/baz bar foo.jpg|embed|link text]]
        
        When an explicit image is displayed using the embed parameter the parameters
        available for internal images will also work.

This one will catch !NoLink's and remove the exclamation mark.

Example:

        !NoLink -> NoLink
        
        !Nocamelcase -> !Nocamelcase

replace

This one will do a simple search and replace for a configurable list of replacements.

Example:

Note that most of these symbols have to be surrounded by whitespaces to prevent the replacement in some abmiguous/unwanted cases.

Quotes:

        some >>beautifully quoted<< text

Asterisk:

        beautiful asterisk * here

Fractions:

        0 < 1/4 < 1/2 < 3/4 < 1

Arrows:

        small -> rightarrow
        
        small <- leftarrow
        
        small <-> leftrightarrow
        
        big => rightarrow

        big <= leftarrow
        
        big <=> leftrightarrow

Dashes:

        small - dash
        
        long -- dash

Symbols:

        copyright (C)
        
        registered (R)

Horizontal Ellipsis:

        The End...

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt::Doc, Konstrukt::Plugin::wiki