PodWiki Markup Documentation

PodWiki uses POD as its markup language. POD is a very simple and easy to learn markup language and it is the standard for perl documentation.

Table of Contents:

    PodWiki Markup Documentation
        PodWiki Markup Examples/Overview
            Lists
                Bullet List
                Numbered List
                Text List (indented text)
                You can also make nested lists and mix list types
            Headings
            Text Formattings
                Bold Text
                Italic Text
                Code
                Preformatted Text
                Avoid linebreaks
                Character Entities
                Horizontal lines
            Hyperlinks
                Links to PodWiki pages
                Links to PodWiki interactive STATE pages
                Links to external websites
                Display Text of Link
                Interwiki Links
            Include Pages
                Include PodWiki Pages
                Include PodWiki interactive STATE pages
                Include External Webpages
            Graphics
                Show an image
                Specify an ALT text attribute for a graphic
                Graphic Links
                Thumbnail Graphic Links
            External Formatters
                Creole Formatter
                WikiShorthand formatter
                Tiki formatter
                TWiki formatter
                HTML formatter
                TEXT formatter
                PERL formatter
                COMMENT formatter
                OPTIONS formatter
                blog formatter
            Tables
            Attributes
            Property Inheritance

 

PodWiki Markup Examples/Overview

Take a look on this table to get an overview of what is possible in PodWiki and how it is done.

For the impatient: visit the PodWikiSample page which shows most of the features.

Lists

PodWikiMarkup

What you get

Bullet List

 =over
 
 =item *
 
 entry 1 entry 1
 
 =item *
 
 entry 2 entry 2
 
 =back 
  • entry 1 entry 1

  • entry 2 entry 2

Numbered List

 =over
 
 =item 1.
 
 entry 1 entry 1
 
 =item 2.
 
 entry 2 entry 2
 
 =back 
1.

entry 1 entry 1

2.

entry 2 entry 2

Text List (indented text)

 =over 4
 
 =item Term to describe1
 
 Describing text2.
 
 =item Term to describe2
 
 Describing text2.
 
 =back 
Term to describe1

Describing text2.

Term to describe2

Describing text2.

You can also make nested lists and mix list types

 =over
 
 =item *
 
 entry 1
 
 =item *
 
 =over
 
 =item 1.
 
 1. entry
 
 =item 2.
 
 =over 4
 
 =item term1
 
 description1
 
 =item term2
 
 description2
 
 =back
 
 =back
 
 =back 
  • entry 1

  • 1.

    1. entry

    2.
    term1

    description1

    term2

    description2

Headings

PodWikiMarkup

What you get

 =head1 Heading 1 

Heading 1

 =head2 Heading 2 

Heading 2

 =head3 Heading 3 

Heading 3

 =head4 Heading 4 

Heading 4

Text Formattings

PodWikiMarkup

What you get

Bold Text

 B<some text> 

some text

Italic Text

 I<some text> 

some text

Code

 C<chmod 751 /etc> 

chmod 751 /etc

Preformatted Text

(prepend each line with one whitespace)

  if(blah)
   abort(); 
 if(blah)
  abort(); 

Avoid linebreaks

 S<This text will appear on one single line> 

This text will appear on one single line

Character Entities

You can use HTML4.0 specification character entity names here.

 E<copy> 

Horizontal lines

Insert a horizontal line in a page using a single paragraph (at least one newline before and after it) just consisting of one or more dashes:

 --- 

Hyperlinks

Links are working as in standard POD but PodWiki doesn't know manpages, it considers such links as "WikiWords" or: as internal PodWiki links.

PodWikiMarkup

What you get

Links to PodWiki pages

Link to an existing page:

 L<Index> 

Link to a non-existing page (this is the way you create new pages, btw.):

 L<YetAnotherPodWikiPage> 

Existing page:

Index

Non-existing page:

YetAnotherPodWikiPage?

Links to PodWiki interactive STATE pages

A state page is an internal PodWiki page which is implemented directly by PodWiki itself. Such pages can not be modified by you or your users (unless you want to edit PodWiki's source code).

Every state page link must begin with intern: or state:.

The following states are avialable at the moment:

* search - execute a search

* newest - show the newest pages

* pageindex - show the page index

* fileindex - show uploaded files (images with thumbnail)

* login - show the login box

Sample:

 LE<lt>intern:login> 

intern:login

Links to external websites

 L<http://www.daemon.de> 

http://www.daemon.de

Display Text of Link

(instead of the link target itself you can choose another text to be displayed):

 L<Daemon Home|http://www.daemon.de> 

Daemon Home

Interwiki Links

PodWiki provides interwiki links. Precede a page link with the name of a known wiki (refer to http://usemod.com/intermap.txt for the current list!) delimited by colon.

 L<WikiPedia:PodWiki> 

WikiPedia:PodWiki

Include Pages

PodWikiMarkup

What you get

Include PodWiki Pages

You can use this feature to load another PodWiki page at this position. PodWiki will render the requested page and print its content at this position.

The whole PodWiki is based on this system. PodWiki itself only loads AutoLoad, which includes several further include directives, and so on. Open AutoLoad with the editor and you will get the point.

 P<PodWikiAbout> 
P<PodWikiAbout?>

Include PodWiki interactive STATE pages

A state page is an internal PodWiki page which is implemented directly by PodWiki itself. Such pages can not be modified by you or your users (unless you want to edit PodWiki's source code).

Every state page inlcude command must begin with intern: or state:.

The following states are avialable at the moment:

state

The core engine of PodWiki. This state must be called everytimes. Take a look at the AutoLoad Page which makes use of this one. If you do not include this, PodWiki will not work at all!

edit_bar

Display the edit bar which provides links to edit the current document and to the revision control info box.

Sample:

 PE<lt>intern:edit_bar> 
toc

Show the table of contents (built from all =head tags).

toc_by_attribute

Show table of all pages matching an attribute. Just add the attribute/value as CGI param to the state, e.g.:

 PE<lt>intern:toc_by_attribute?topic=Main> 
comments

Includes the comment feature to a page. The recommended position where to include this state is the end of a page. All posted comments will be displayed. Visitors are able to post new comments and it is possible to reply to a comment.

The root-User is able to remove comments. Just login as root, visit the page where the comment to be removed is posted and click the "remove comment" link.

Comments can be written in PodWikiMarkup or WikiShorthand markup.

cloud

Shows a tag cloud of all indexed words of all pages.

tags_per_page

Lists all tags of current page.

Include External Webpages

PodWiki can also load external webpages instead of PodWiki pages. Just replace the page name with an uri which starts with http://:

Please note that the complete head tag will be removed to protect the page design of PodWiki. Also body and html tags will be removed.

 P<http://www.bankleitzahlen.de/ibanrechner.php> 

Moved Permanently

The document has moved here.


Apache/2.2.3 (CentOS) Server at www.bankleitzahlen.de Port 80

Graphics

PodWikiMarkup

What you get

Show an image

(you can upload images to PodWiki from the editor form! If you intent to use uploaded graphics do not use path specifications, just the filename.)

 G<daemon.png> 

/images/daemon.png

Specify an ALT text attribute for a graphic

 G<daemon.png|daemon home> 

daemon home

Graphic Links

 L<G<daemon.png>|http://www.daemon.de> 

/images/daemon.png

Thumbnail Graphic Links

 T<daemon.png> 

daemon.png

External Formatters

In perl POD you can use =begin [formatter] to indicate that the following text has to be rendered by an external "formatter". A "formatter" is a special render mode which directly influences how PodWiki displays the content inside a special formatter block. PodWiki supports this feature and understands the following formatters:

The following formatter tags are recognized on this PodWiki:

The formatters are further described below:

PodWikiMarkup

What you get

Creole Formatter

The Creole formatter is the default formatter used if a page is not written in PerlPod.

Please refer to the CreoleSample page for more details!

WikiShorthand formatter

The NATURAL formatter is also called WikiShorthand and allows you to write pages the traditional WIKI way. Learn more about WikiShorthand.

 =begin wikishorthand
 
 Headline
 --------
 
 This one paragraph.
 
 And this is another paragraph.
 
 *Bold* and /italic/ text format is supported.
 
 Of course links are working too: [PodWikiMarkup].
 Write external links by just entering the URL: http://god.org
 
 Include graphics just by writing the image filename: ok.png.
 
 Lists are possible too:
 
 o item one
 
 o item two
 
 You can use PodWiki variables: $gohome.
 
 =end wikishorthand 

Headline

This one paragraph.

And this is another paragraph.

Bold and italic text format is supported.

Of course links are working too: PodWikiMarkup. Write external links by just entering the URL: http://god.org

Include graphics just by writing the image filename: ok.png.

Lists are possible too:

  • item one

  • item two

You can use PodWiki variables: gohome.

Tiki formatter

The tiki formatter adds TikiWiki(http://tikiwiki.org/) compatibility to PodWiki. Learn more about TikiMarkup.

 =begin tiki
 
 ~~red:red text~~
 
 ::centered text::
 
 * list1
 * item2
 
 ''italic text''
 
 __Bold text__
 
 !   Head1
 !!  Head2
 !!! Head3
 
 Separator:
 ---
 
 Link:
 PodWikiMarkup
 
 ^box^
 
 <verbatim>
 class animal {
   void purr() {
     return 0;
   }
 }
 </verbatim>
 
 =end tiki 

red text

centered text

  • list1
  • item2

italic text

Bold text

Head1

Head2

Head3

Separator:


Link: PodWikiMarkup

box


class animal {
  void purr() {
    return 0;
  }
}

TWiki formatter

The TWiki formatter adds TWiki(http://www.twiki.org/) compatibility to PodWiki. Learn more about TWikiMarkup.

 
 =begin twiki
 
 ---+ Head1
 ---++ Head2
 ---+++ Head3
 
 Paragraph one
 
 Paragraph two
 
 *Bold*  _Italic_  __Bold italic__ =Fixed font=
 
 <verbatim>
 // verbatim text
 class CatAnimal {
   void purr() {
     <code here>
   }
 }
 </verbatim>
 
 A wiki link: PodWikiMarkup
 
 %RED% Colored %ENDCOLOR% %BLUE% Text %ENDCOLOR%
 
 =end 

Head1

Head2

Head3

Paragraph one

Paragraph two

Bold Italic Bold italic Fixed font

// verbatim text
class CatAnimal {
  void purr() {
    <code here>
  }
}

A wiki link: PodWikiMarkup

RED Colored END BLUE Text END

HTML formatter

The formatter for 'html' keeps the text 1:1 as you wrote it. You can use it to insert plain HTML code, a table for instance, which is not directly supported by POD.

 =begin html
 
 <center>centered text</center>
 
 =end 
centered text

TEXT formatter

This formatter works similar to the 'html' formatter but it inserts the text between pre tags. Use this for code snippets or the like.

txt or ascii can also be used as synonyms for text.

 =begin txt
 
 if(online) {
   inet_fd->disconnect();
 }
 
 =end 
if(online) {
  inet_fd->disconnect();
} 

PERL formatter

The 'perl' formatter allows you to insert perl code into your WikiPage which gets evaluated by PodWiki. This feature makes PodWiki a very powerfull tool. You can use it for example to add a formular to your PodWiki site.

You must print to STDOUT what have to be displayed on the page.

 =begin perl
 
 print scalar localtime(time);
 
 =end 

Please note that this formatter is turned off by default. It may harm your system turning it on. Do it at your own risk. PodWiki makes no security checks on the code executed at the moment!

<enable_perl_formatter::OFF>

COMMENT formatter

Everything inside a comment block will not rendered by PodWiki at all.

 =begin comment
 
 This will not be shown.
 
 =end 

It is also possible to insert HTML comments anywhere in your POD or Shorthand page:

 <!-- comment --> 

OPTIONS formatter

Everything inside an options block will not rendered by PodWiki but instead used to control its behavior.

Currently only Authentication options are supported.

 =begin options
 
 read  = root
 write = root
 
 =end 

blog formatter

This formatter will render existing podwiki pages together on a new page as blog postings. Everything inside the block will be considered as blog configuration parameters.

 =begin blog
 
 category = Blogging
 user     = henry
 postings = 10 
 =end 

To create a blog, you'll have to create a new attribute on the SiteAdmin page. Use this attribute as category. All pages classified under this category will be shown on the blog.

The user parameter tells the blog formatter to show a small admin menu for the user if he is logged in. From this menu he will be able to add values to the attribute created previously. So, a blog user can maintain his own categories for blog posts.

The number of postings (wiki pages) shown on the blog page can be tweaked via the postings parameter.

Each blog posting will be rendered separately so it can be any valid PodWiki page with all features PodWiki provides. The title of a posting will be the page name followed by the posting itself and finally followed by a footer showing the user who wrote it, the revision, the date and the number of comments added to the page, if any.

Example blog

Tables

Tables can be written using POD (see below) or PodWikiFormatterTiki.

PodWikiMarkup

What you get

You can write almost any type of tables using POD. Please note that this POD is not valid POD from the perl point of view. In other words: There is no renderer which understands this beside PodWiki.

A table starts with:

 =table 

and ends with:

 =tableback 

The table contains one or more rows. A row starts with:

 =row 

and ends with:

 =rowback 

A row itself can contain one or more cells. Cells will be written as:

 =cell 

Everything below a cell is the content of the table cell until the next cell or a =rowback occurs.

The commands =table =row =cell accept HTML options, which can be used to control the table design or the like. Multiple options can be assigned, separated by comma, spaces are not allowed!

If you want to mark a cell as a head cell, assign the special (non-HTML) option type=head to the cell.

Example:

 
 =table border=0
 
 =row
 
 =cell type=head,bgcolor=#cfcfcf
 
 User
 
 =cell type=head,bgcolor=#cfcfcf
 
 Birthday
 
 =rowback
 
 =row
 
 =cell
 
 max
 
 =cell
 
 08.09.1970
 
 =rowback
 
 =tableback 

User

Birthday

max

08.09.1970

Attributes

The administrator can define any number of attributes with a list of values for each of them. Those attributes can then be used later by site editors to classify particular PodWiki pages.

This allows you to have several "topic" or "pagetypes", etc. There is no limitation about attributes.

Attributes can be used for searching and browsing. The search page includes an attribute selection area, where you can search by attributes.

There also exists an internal state toc_by_value (see above!) which generates an index page on pages matching some attribute(s).

Property Inheritance

Page properties (options and attributes) will be inherited by the first referencing page during page creation. E.g. if you edit an existing page and add a new link to a non-existing page (which is the way to create new pages), the new page will inherit all properties of the page where you added the link the first time.

This allows you to keep track of the page context or permission settings. For example you could have an attribute "Topic" with an value "internal". Then you could create a new page (e.g. the "entry page" for this "topic") which is password protected. If you create further pages from this one all those new pages will be classified under "topic" == "internal" and will be password protected too.