=begin options

write = root

=end

=begin comment

$Id: PodWikiMarkup,v 1.6 2004/05/07 14:29:45 dabright Exp $

Table which describes how to do things along with examples.
(requires 0.7.4 or higher)

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

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

=head3 Lists

=table cellpadding="5",width="100%",frame="box",rules="group",border="1"

=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback



=row valign="bottom"

=cell

=head4 Bullet List

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

=cell

=over

=item *

entry 1 entry 1

=item *

entry 2 entry 2

=back

=rowback

=row valign="bottom"

=cell

=head4 Numbered List

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


=cell


=over

=item 1.

entry 1 entry 1

=item 2.

entry 2 entry 2

=back

=rowback

=row valign="bottom"

=cell

=head4 Text List (indented text)

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


=cell


=over 4

=item Term to describe1

Describing text2.

=item Term to describe2

Describing text2.

=back

=rowback

=row valign="bottom"

=cell

=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

=cell


=over

=item *

entry 1

=item *

=over

=item 1.

1. entry

=item 2.

=over 4

=item term1

description1

=item term2

description2

=back

=back

=back

=rowback

=tableback









=head3 Headings


=table cellpadding="5",width="100%",frame="box",rules="group",border="1"



=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback



=row valign="bottom"

=cell

 =head1 Heading 1

=cell

<h1>Heading 1</h1>

=rowback



=row valign="bottom"

=cell

 =head2 Heading 2

=cell

<h2>Heading 2</h2>

=rowback



=row valign="bottom"

=cell

 =head3 Heading 3

=cell

<h3>Heading 3</h3>

=rowback


=row valign="bottom"

=cell

 =head4 Heading 4

=cell

<h4>Heading 4</h4>

=rowback

=tableback






=head3 Text Formattings

=table cellpadding="5",width="100%",frame="box",rules="group",border="1"

=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback



=row valign="bottom"

=cell

=head4 Bold Text

=begin text

 BE<lt>some text>

=end

=cell

B<some text>

=rowback



=row valign="bottom"

=cell

=head4 Italic Text

=begin text

 IE<lt>some text>

=end

=cell

I<some text>

=rowback



=row valign="bottom"

=cell

=head4 Code

=begin text

 CE<lt>chmod 751 /etc>

=end

=cell

C<chmod 751 /etc>

=rowback



=row valign="bottom"

=cell

=head4 Preformatted Text

(prepend each line with one whitespace)

  if(blah)
   abort();

=cell

 if(blah)
  abort();

=rowback



=row valign="bottom"

=cell

=head4 Avoid linebreaks

=begin text

 SE<lt>This text will appear on one single line>

=end

=cell

S<This text will appear on one single line>

=rowback



=row valign="bottom"

=cell

=head4 Character Entities

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

=begin text

 EE<lt>copy>

=end

=cell

E<copy>

=rowback

=tableback











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

=table cellpadding="5",width="100%",frame="box",rules="group",border="1"

=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback

=row valign="bottom"

=cell

=head4 Links to PodWiki pages

Link to an existing page:

=begin text

 LE<lt>PodWikiIndex>

=end

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

=begin text

 LE<lt>YetAnotherPodWikiPage>

=end

=cell

Existing page:

L<PodWikiIndex>

Non-existing page:

L<YetAnotherPodWikiPage>

=rowback



=row valign="bottom"

=cell

=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

* fileindex - show uploaded files (images with thumbnail)

* login - show the login box

Sample:

 LE<lt>intern:login>

=cell

L<intern:login>

=rowback



=row valign="bottom"

=cell

=head4 Links to external websites

=begin text

 LE<lt>http://www.daemon.de>

=end

=cell

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

=rowback



=row valign="bottom"

=cell

=head4 Display Text of Link

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

=begin text

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

=end

=cell

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

=rowback

=tableback





=head3 Include Pages

=table cellpadding="5",width="100%",frame="box",rules="group",border="1"

=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback

=row valign="bottom"

=cell

=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

 PE<lt>PodWikiAbout>

=end

=cell

P<PodWikiAbout>

=rowback



=row valign="bottom"

=cell

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

=over

=item B<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!

=item B<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>

=item B<toc>

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

=item B<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>

=item B<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 B<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 L<PodWikiMarkup> or L<WikiShorthand> markup.

=back

=cell

P<intern:edit_bar>

=rowback



=row valign="bottom"

=cell

=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

 PE<lt>http://www.bankleitzahlen.de/ibanrechner.php>

=end

=cell

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

=rowback

=tableback







=head3 Graphics

=table cellpadding="5",width="100%",frame="box",rules="group",border="1"

=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback



=row valign="bottom"

=cell

=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

 GE<lt>daemon.png>

=end

=cell

G<daemon.png>

=rowback



=row valign="bottom"

=cell

=head4 Specify an ALT text attribute for a graphic

=begin text

 GE<lt>daemon.png|daemon home>

=end

=cell

G<daemon.png|daemon home>

=rowback



=row valign="bottom"

=cell

=head4 Graphic Links

=begin text

 LE<lt>GE<lt>daemon.png>|http://www.daemon.de>

=end

=cell

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

=rowback



=row valign="bottom"

=cell

=head4 Thumbnail Graphic Links

=begin text

 TE<lt>daemon.png>

=end

=cell

T<daemon.png>

=rowback

=tableback






=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 how PodWiki displays the content inside
a special formatter block. PodWiki supports this feature
and understands the following formatters:

P<intern:formatters>

The formatters are further described below:

=table cellpadding="5",width="100%",frame="box",rules="group",border="1"

=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback



=row valign="bottom"

=cell

=head4 WikiShorthand formatter

The NATURAL formatter is also called B<WikiShorthand> and allows you
to write pages the traditional WIKI way. L<Learn more about WikiShorthand|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

=cell

=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

=rowback



=row valign="bottom"

=cell

=head4 Tiki formatter

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

 =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

=cell

=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

=rowback



=row valign="bottom"

=cell

=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
 
 <center>centered text</center>
 
 =end

=cell

=begin html

<center>centered text</center>

=end html

=rowback



=row valign="bottom"

=cell

=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

=cell

=begin txt

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

=end

=rowback



=row valign="bottom"

=cell

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

=cell

=begin perl

print scalar localtime(time);

=end

=rowback



=row valign="bottom"

=cell

=head4 COMMENT formatter

Everything inside a B<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 -->

=cell

=begin comment

 This will not be shown.

=end

=rowback



=row valign="bottom"

=cell

=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

=rowback

=tableback




=head3 Tables

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

=table cellpadding="5",width="100%",frame="box",rules="group",border="1"

=row valign="bottom",bgcolor="#ffffcc"

=cell type=head

PodWikiMarkup

=cell type=head

What you get

=rowback



=row valign="bottom"

=cell

You can write almost any type of tables using POD. Please note that
this POD is not B<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 B<rows>. A row starts with:

 =row

and ends with:

 =rowback

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

 =cell

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

The commands B<=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 B<head> cell, assign the special
(non-HTML) option B<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

=cell

=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

=rowback

=tableback


=head3 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 B<toc_by_value> (see above!)
which generates an index page on pages matching some attribute(s).


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

=cut
