=begin options

write = root

=end

=begin comment

$Id$

Table which describes how to do things along with examples.

=end

=head1 PodWiki Markup Documentation

B<PodWiki> uses L<POD|PerlPod> as its
markup language. POD is a very simple and easy to learn markup language and
it is the standard for perl documentation.

I<Table of Contents:>

P<intern:toc>

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

=head3 Lists

=begin html

<table cellpadding="5" width="100%" frame="box" rules="group" border="1">
 <tr valign="bottom" bgcolor="#ffffcc">
  <th>PodWikiMarkup</th><th>What you get</th>
 </tr>
 <tr valign="bottom">
  <td>

=end

=head4 Bullet List

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

=begin html

  </td>
  <td>

=end

=over

=item *

entry 1 entry 1

=item *

entry 2 entry 2

=back

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Numbered List

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


=begin html

  </td>
  <td>

=end

=over

=item 1.

entry 1 entry 1

=item 2.

entry 2 entry 2

=back


=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Text List (indended text)

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


=begin html

  </td>
  <td>

=end

=over 4

=item Term to describe1

Describing text2.

=item Term to describe2

Describing text2.

=back


=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

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

=begin html

  </td>
  <td>

=end

=over

=item *

entry 1

=item *

=over

=item 1.

1. entry

=item 2.

=over 4

=item term1

description1

=item term2

description2

=back

=back

=back



=begin html

  </td>
 </tr>
</table>

=end


















=head3 Headings

=begin html

<table cellpadding="5" width="100%" frame="box" rules="group" border="1">
 <tr valign="bottom" bgcolor="#ffffcc">
  <th>PodWikiMarkup</th><th>What you get</th>
 </tr>
 <tr valign="bottom">
  <td>

=end

 =head1 Heading 1

=begin html

  </td>
  <td>

<h1>Heading 1</h1>

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

 =head2 Heading 2

=begin html

  </td>
  <td>

<h2>Heading 2</h2>

  </td>
 </tr>
 <tr valign="bottom">
  <td>

=end

 =head3 Heading 3

=begin html

  </td>
  <td>

<h3>Heading 3</h3>

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

 =head4 Heading 4

=begin html

  </td>
  <td>

<h4>Heading 4</h4>

  </td>
 </tr>
</table>

=end






=head3 Text Formattings


=begin html

<table cellpadding="5" width="100%" frame="box" rules="group" border="1">
 <tr valign="bottom" bgcolor="#ffffcc">
  <th>PodWikiMarkup</th><th>What you get</th>
 </tr>
 <tr valign="bottom">
  <td>

=end

=head4 Bold Text

=begin text

 B&lt;some text>

=end

=begin html

  </td>
  <td>

=end

B<some text>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Italic Text

=begin text

 I&lt;some text>

=end

=begin html

  </td>
  <td>

=end

I<some text>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Code

=begin text

 C&lt;chmod 751 /etc>

=end

=begin html

  </td>
  <td>

=end

C<chmod 751 /etc>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Preformatted Text

(prepend each line with one whitespace)

  if(blah)
   abort();

=begin html

  </td>
  <td>

=end

 if(blah)
  abort();

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Avoid linebreaks

=begin text

 S&lt;This text will appear on one single line>

=end

=begin html

  </td>
  <td>

=end

S<This text will appear on one single line>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Character Entities

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

=begin text

 E&lt;copy>

=end

=begin html

  </td>
  <td>

=end

E<copy>

=begin html

  </td>
 </tr>
</table>

=end












=head3 Hyperlinks

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

=begin html

<table cellpadding="5" width="100%" frame="box" rules="group" border="1">
 <tr valign="bottom" bgcolor="#ffffcc">
  <th>PodWikiMarkup</th><th>What you get</th>
 </tr>
 <tr valign="bottom">
  <td>

=end


=head4 Links to PodWiki pages

Link to an existing page:

=begin text

 L&lt;PodWikiIndex>

=end

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

=begin text

 L&lt;YetAnotherPodWikiPage>

=end


=begin html

  </td>
  <td>

=end

Existing page:

L<PodWikiIndex>

Non-existing page:

L<YetAnotherPodWikiPage>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Links to PodWiki interactive STATE pages

A B<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 B<intern:> or B<state:>.

The following states are avialable at the moment:

* search - execute a search

* newest - show the newest pages

* pageindex - show the page index

* login - show the login box

Sample:

 L&lt;intern:login>

=begin html

  </td>
  <td>

=end

L<intern:login>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
  <td>

=end

=head4 Links to external websites

=begin text

 L&lt;http://www.daemon.de>

=end

=begin html

  </td>
  <td>

=end

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

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Display Text of Link

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

=begin text

 L&lt;Daemon Home|http://www.daemon.de>

=end

=begin html

  </td>
  <td>

=end

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

=begin html

  </td>
 </tr>
</table>

=end


=head3 Include Pages

=begin html

<table cellpadding="5" width="100%" frame="box" rules="group" border="1">
 <tr valign="bottom" bgcolor="#ffffcc">
  <th>PodWikiMarkup</th><th>What you get</th>
 </tr>
 <tr valign="bottom">
  <td>

=end

=head4 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 B<AutoLoad>, which includes several further include directives,
and so on. Open AutoLoad with the editor and you will get the point.

=begin text

 P&lt;PodWikiAbout>

=end

=begin html

  </td>
  <td>

=end

P<PodWikiAbout>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Include PodWiki interactive STATE pages

A B<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 B<intern:> or B<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 B<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. 

* toc - show the table of contents (build from all =head tags).

Sample:

 P&lt;intern:edit_bar>

=begin html

  </td>
  <td>

=end

P<intern:edit_bar>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
  <td>

=end

=head4 Include External Webpages

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

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

=begin text

 P&lt;http://www.bankleitzahlen.de/ibanrechner.php>

=end

=begin html

  </td>
  <td>

=end

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

=begin html

  </td>
 </tr>
</table>

=end





=head3 Graphics

=begin html

<table cellpadding="5" width="100%" frame="box" rules="group" border="1">
 <tr valign="bottom" bgcolor="#ffffcc">
  <th>PodWikiMarkup</th><th>What you get</th>
 </tr>
 <tr valign="bottom">
  <td>

=end

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

=begin text

 G&lt;daemon.png>

=end

=begin html

  </td>
  <td>

=end

G<daemon.png>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Specify an ALT text attribute for a graphic

=begin text

 G&lt;daemon.png|daemon home>

=end

=begin html

  </td>
  <td>

=end

G<daemon.png|daemon home>

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 Graphic Links

=begin text

 L&lt;G&lt;daemon.png>|http://www.daemon.de>

=end

=begin html

  </td>
  <td>

=end

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

=begin html

  </td>
 </tr>
</table

=end





=head3 External Formatters

In perl POD you can use B<=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 PodWiki how it displays the content inside
a special formatter block. PodWiki supports this feature
and understands the following formatters:

=begin html

<table cellpadding="5" width="100%" frame="box" rules="group" border="1">
 <tr valign="bottom" bgcolor="#ffffcc">
  <th>PodWikiMarkup</th><th>What you get</th>
 </tr>
 <tr valign="bottom">
  <td>

=end

=head4 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
 
 &lt;center>centered text&lt;/center>
 
 =end

=begin html

  </td>
  <td>

<center>centered text</center>

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 TEXT formatter

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

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

 =begin txt

 if(online) {
   inet_fd->disconnect();
 }

 =end

=begin html

  </td>
  <td>

=end

=begin txt

if(online) {
  inet_fd->disconnect();
}

=end

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 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 B<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. B<PodWiki> makes no security
checks on the code executed at the moment!

=begin html

  </td>
  <td>

=end

=begin perl

print scalar localtime(time);

=end

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 COMMENT formatter

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

 =begin comment

 This will not be shown.

 =end

=begin html

  </td>
  <td>

=end

=begin comment

 This will not be shown.

=end

=begin html

  </td>
 </tr>
 <tr valign="bottom">
 <td>

=end

=head4 OPTIONS formatter

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

Currently only L<Authentication|PodWikiAuth> options are supported.

 =begin options

 read  = root
 write = root

 =end

=begin html

  </td>
  <td>
  </td>
 </tr>
</table

=end

=head3 Variables

You can insert some predefined variables somewhere in your pages.
A variable must begin with the dollar character!

The following variables are supported at the moment:

B<me> - the scriptname of PodWiki, usefull for building uri's.

B<page> - the name of the current PodWikiPage. 


=cut



