Page Source for PodWikiMarkup
=begin options
write = root
=end
=begin comment
$Id: PodWikiMarkup,v 1.2 2007/09/21 07:51:01 root-83.143.239.128
Experimental $
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
=row valign="bottom"
=cell
=head4 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:
=begin text
---
=end
=cell
---
=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>Index>
=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<Index>
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
=row valign="bottom"
=cell
=head4 Interwiki Links
PodWiki provides interwiki links. Precede a page link with the name of
a known wiki (refer to L<http://usemod.com/intermap.txt> for the
current list!) delimited by colon.
=begin text
LE<lt>WikiPedia:PodWiki>
=end
=cell
L<WikiPedia:PodWiki>
=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.
=item B<cloud>
Shows a tag cloud of all indexed words of all pages.
=item B<tags_per_page>
Lists all tags of current page.
=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 Creole Formatter
The L<Creole> formatter is the default formatter used if a page
is not written in L<PerlPod>.
=cell
Please refer to the L<CreoleSample> page for more details!
=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 TWiki formatter
The TWiki formatter adds TWiki(L<http://www.twiki.org/>)
compatibility to PodWiki. L<Learn more about
TWikiMarkup|PodWikiFormatterTWiki>.
=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
=cell
=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
=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
=row valign="bottom"
=cell
=head4 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
L<SiteAdmin|intern:site_admin> page. Use this attribute as
B<category>. All pages classified under this category will be
shown on the blog.
The B<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 B<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.
=cell
L<Example blog|http://www.daemon.de/sciplog>
=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