Diamondcard.us Wiki

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 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>	Bad Request Your browser sent a request that this server could not understand.

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>

Bad Request

Your browser sent a request that this server could not understand.

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>
Specify an ALT text attribute for a graphic G<daemon.png\|daemon home>
Graphic Links L<G<daemon.png>\|http://www.daemon.de>
Thumbnail Graphic Links T<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:

creole
blog
twiki
html
text
perl
bbcode
options
tiki
wikishorthand

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

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

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.

Diamondcard.us Wiki

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

Heading 1

Heading 2

Heading 3

Heading 4

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

Bad Request

Graphics

Show an image

Specify an ALT text attribute for a graphic

Graphic Links

Thumbnail Graphic Links

External Formatters

Creole Formatter

WikiShorthand formatter

Headline

Tiki formatter

Head1

Head2

Head3

TWiki formatter

Head1

Head2

Head3

HTML formatter

TEXT formatter

PERL formatter

COMMENT formatter

OPTIONS formatter

blog formatter

Tables

Attributes

Property Inheritance