Update of /cvsroot/php-blog/serendipity/bundled-libs/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1804/docs
Added Files:
HomePage.wiki.txt SamplePage.wiki.txt
SmashWordsTogether.wiki.txt TextWikiProposal.wiki.txt
TokenRuleKeys.wiki.txt WikiPage.wiki.txt
WordsSmashedTogether.wiki.txt free links.wiki.txt index.php
stylesheet.css
Log Message:
Added PEAR:Text/Wiki (latest 0.8.2) bundled library
--- NEW FILE: HomePage.wiki.txt ---
+ Text_Wiki
%%TOC%%
++ Overview and Background
We assume you know what [http://c2.com/cgi/wiki Wiki] is. The Wiki Way entails a lot more than just rules for structured-text markup, but that's the only part of the Wiki Way that this package, {{Text_Wiki}}, is concerned with.
The {{Text_Wiki}} package allows you to transform text structured using Wiki rules into any defined target output format. For example, you can convert...
* Tavi-style Wiki text into XHTML
* Original C2-style Wiki text into XML
* !MeatBall style Wiki text into !LaTeX
* Any other Wiki markup rules into any other format (provided it's programmed properly ;-)
{{Text_Wiki}} achieves this level of flexibility by using one class per transformation rule, instead of using a monolithic set of functions. Each Text_Wiki rule has these methods:
* A constructor that links back to the "master" Text_Wiki class, which the source text as well as any optional confugration parameters
* A parse() method that looks through the source text for strings that match a regular expression
* A process() method that takes the parsed regular expression matches and converts them to an intermediate "meta-format" (generally a delimited token that is re-inserted into the source text, along with a set of options for that specific token)
* A render() method that replaces a saved token with output for a specific target format (e.g., XHTML or !LaTeX).
{{Text_Wiki}} draws its inspiration from a number of codebases, most notably !WikkiTikkiTavi and coWiki; while no code has been directly copied from those codebases, they were indispensible in learning how to process Wiki text.
Also see these pages for more information:
* SamplePage -- for a full list of default markup rules
* TokenRuleKeys -- for a list of the tokens keys generated by different rules
* TextWikiProposal -- a modified version of the initial Text_Wiki proposal to PEAR
++ What Text_Wiki Does Not Do
The {{Text_Wiki}} package does not implement storage, saving, editing, diffs, page counts, and so on. Those functions are more properly the domain of a full Wiki application and environment, which is outside the stated {{Text_Wiki}} goals (i.e., to transform Wiki text according to defined rules for a target output format).
++ Using Text_Wiki
Here is a quick example of how to use {{Text_Wiki}} to parse from the default markup style (combined from [http://tavi.sourceforge.net/ Tavi] and [http://develnet.org/ coWiki]), do some basic filtering, and render to XHTML.
<php>
// require the Text_Wiki class and create an instance of a new wiki
// parse-and-render object
require_once 'Text/Wiki.php';
$wiki = new Text_Wiki();
// load up some source text
$text = file_get_contents('sample.wiki.txt');
// transform the text using the default rules for parsing and rendering.
// the extra \n newlines seem to help with some parsing rules.
echo $wiki->transform("\n" . $text . "\n");
</php>
++ Text_Wiki Options
When you create an instance of Text_Wiki, you can pass a set of options as an associative array.
The array keys for the options are:
|| '''option key''' || '''variable type''' || '''description''' ||
|| {{delim}} || string || the source text delimiter for tokens ||
|| {{interwiki}} || array || interwiki site names and URLs ||
|| {{new_text}} || string || link-text for new pages ||
|| {{new_url}} || string || URL for new pages ||
|| {{pages}} || array || list of pages existing in the wiki ||
|| {{rules}} || array || the list of rules to be applied to source text ||
|| {{view_url}} || string || URL for viewing pages in the wiki ||
For example:
<php>
// the list of rules, and in which order, to use when
// transforming structured text; the key is the name to use for
// identifying tokens for the rule, and the value is the file
// name of the rule class.
$rules = array(
'prefilter' => 'Text/Wiki/Rule/prefilter.php',
'delimiter' => 'Text/Wiki/Rule/delimiter.php',
'code' => 'Text/Wiki/Rule/code.php',
'phpcode' => 'Text/Wiki/Rule/phpcode.php',
'html' => 'Text/Wiki/Rule/html.php',
'heading' => 'Text/Wiki/Rule/heading.php',
'horiz' => 'Text/Wiki/Rule/horiz.php',
'blockquote' => 'Text/Wiki/Rule/blockquote.php',
'deflist' => 'Text/Wiki/Rule/deflist.php',
'table' => 'Text/Wiki/Rule/table.php',
'list' => 'Text/Wiki/Rule/list.php',
'toc' => 'Text/Wiki/Rule/toc.php',
'paragraph' => 'Text/Wiki/Rule/paragraph.php',
'raw' => 'Text/Wiki/Rule/raw.php',
'phplookup' => 'Text/Wiki/Rule/phplookup.php',
'url' => 'Text/Wiki/Rule/url.php',
'interwiki' => 'Text/Wiki/Rule/interwiki.php',
'freelink' => 'Text/Wiki/Rule/freelink.php',
'wikilink' => 'Text/Wiki/Rule/wikilink.php',
'strong' => 'Text/Wiki/Rule/strong.php',
'bold' => 'Text/Wiki/Rule/bold.php',
'emphasis' => 'Text/Wiki/Rule/emphasis.php',
'italic' => 'Text/Wiki/Rule/italic.php',
'tt' => 'Text/Wiki/Rule/tt.php',
'superscript' => 'Text/Wiki/Rule/superscript.php',
'revise' => 'Text/Wiki/Rule/revise.php',
'entities' => 'Text/Wiki/Rule/entities.php',
'tighten' => 'Text/Wiki/Rule/tighten.php'
);
// the list of InterWiki names and URLs
$interwiki = array(
'MeatBall' => 'http://www.usemod.com/cgi-bin/mb.pl?',
'Advogato' => 'http://advogato.org/',
'Wiki' => 'http://c2.com/cgi/wiki?'
);
// the URL used to view local WikiWeb pages
$view_url = "http://example.com/wiki.php?page=";
// create a Text_Wiki options array
$options = array(
'rules' => $rules,
'interwiki' => $interwiki,
'view_url' => $view_url
);
// instantiate a Text_Wiki object with the options
$wiki =& new Text_Wiki($options);
</php>
+++ {{delim}}
The {{delim}} option is a string, and sets the value of the delimiter character used to mark a token number in the Wiki source text. When a rule needs to set a token, it replaces the source text with a token number surrounded by this delimiter.
The default delmiter is {{```\xFF```}}, but you can change it to anything you like. Be aware that the token you choose may be subject to Wiki rules, so be sure to choose something that the rules don't affect.
For example:
<php>
// use a nullchar delimiter
$options['delim'] = '\x00');
</php>
+++ {{interwiki}}
The {{interwiki}} option is an associative array where the key is an !InterWiki site name, and the value is the URL for pages at that site. For example, if you want to refer to the !MeatBall site in your pages using the !InterWiki rule, you need to pass this option.
<php>
// name and link to the MeatBall Wiki
$options['interwiki'] = array(
'MeatBall' => 'http://www.usemod.com/cgi-bin/mb.pl?'
);
</php>
+++ {{new_text}}
The {{new_text}} option is a string. If your wiki source text refers to a page that does not exist (as provided by the {{pages}} option) then it is considered to be a "new" page; thus, the Text_Wiki will link to a web page for creating new pages.
The {{new_text}} option specifies the literal linked text to be appended to the page name on display. It can be text proper, or an HTML image tag, or anything else.
See also the {{new_url}} option.
<php>
// use a question mark and a space
$options['new_text'] = '? ';
// use an image
$options['new_text'] = '<img src="http://example.com/newpage.gif />';
</php>
+++ {{new_url}}
The {{new_url}} option is a string. If your wiki source text refers to a page that does not exist (as provided by the {{pages}} option) then it is considered to be a "new" page; thus, Text_Wiki will link to a web page for creating new pages.
The {{new_url}} specifies the URL to the application-specific page creation utility.
See also the {{new_text}} option.
<php>
// link to the new-page script
$options['new_url'] = 'http://example.com/newpage.php?page=';
</php>
+++ {{pages}}
The {{pages}} option is a sequential array where each element is the name of page in the Wiki. See also the {{view_url}} option.
<php>
// only three pages in this wiki
$options['pages'] = array(
'HomePage',
'SamplePage',
'TokenRuleKeys'
)
</php>
+++ {{rules}}
This option is a associative array; it specifies the rule names to apply to wiki source text. The key is the token name to be used when idenitfying text marked by that rule, and the value is the file name of the rule class. (Previously, rule class names and rule file names had to adhere to a specific convention; that is no longer necessary.)
<php>
$options['rules'] = array(
'prefilter' => 'Text/Wiki/Rule/prefilter.php',
'delimiter' => 'Text/Wiki/Rule/delimiter.php',
'code' => 'Text/Wiki/Rule/code.php',
'phpcode' => 'Text/Wiki/Rule/phpcode.php',
'html' => 'Text/Wiki/Rule/html.php',
'heading' => 'Text/Wiki/Rule/heading.php',
'horiz' => 'Text/Wiki/Rule/horiz.php',
'blockquote' => 'Text/Wiki/Rule/blockquote.php',
'deflist' => 'Text/Wiki/Rule/deflist.php',
'table' => 'Text/Wiki/Rule/table.php',
'list' => 'Text/Wiki/Rule/list.php',
'toc' => 'Text/Wiki/Rule/toc.php',
'paragraph' => 'Text/Wiki/Rule/paragraph.php',
'raw' => 'Text/Wiki/Rule/raw.php',
'phplookup' => 'Text/Wiki/Rule/phplookup.php',
'url' => 'Text/Wiki/Rule/url.php',
'interwiki' => 'Text/Wiki/Rule/interwiki.php',
'freelink' => 'Text/Wiki/Rule/freelink.php',
'wikilink' => 'Text/Wiki/Rule/wikilink.php',
'strong' => 'Text/Wiki/Rule/strong.php',
'bold' => 'Text/Wiki/Rule/bold.php',
'emphasis' => 'Text/Wiki/Rule/emphasis.php',
'italic' => 'Text/Wiki/Rule/italic.php',
'tt' => 'Text/Wiki/Rule/tt.php',
'superscript' => 'Text/Wiki/Rule/superscript.php',
'revise' => 'Text/Wiki/Rule/revise.php',
'entities' => 'Text/Wiki/Rule/entities.php',
'tighten' => 'Text/Wiki/Rule/tighten.php'
);
</php>
The above is the default list of rules. If you want to use your own (for example) {{wikilink}} rule to override the default rule, you can replace the array element with the path to your modified rule:
<php>
// [snip] set up $options
$wiki =& new Text_Wiki($options);
// replace the 'wikilink' default rule
$wiki->rules['wikilink'] = '/path/to/my/rules/my_wikilink.php';
</php>
+++ {{view_url}}
The {{view_url}} option is a string that specifies the URL to the application-specific page viewing utility. If your wiki source text refers to a page listed in the {{pages}} option array, the Text_Wiki rules for 'wiki' and 'wikifreelink' will create a link to that page using this URL.
<php>
// link to the page-viewing script
$options['view_url'] = 'http://example.com/wiki.php?page=';
</php>
--- NEW FILE: SamplePage.wiki.txt ---
+ Sample Page for Text_Wiki Default Markup
%%TOC%%
----
++ General Notes
The markup described on this page is for the default {{Text_Wiki}} rules; \
it is a combination of the [http://tavi.sourceforge.net WikkTikkiTavi] \
and [http://develnet.org/ coWiki] markup styles.
All text is entered as plain text, and will be converted to HTML entities as \
necessary. This means that {{<}}, {{>}}, {{&}}, and so on are converted for \
you (except in special situations where the characters are Wiki markup; \
Text_Wiki is generally smart enough to know when to convert and when not to).
Just hit "return" twice to make a paragraph break. If you want \
to keep the same logical line but have to split it across \
two physical lines (such as when your editor only shows a certain number \
of characters per line), end the line with a backslash {{\}} and hit \
return once. This will cause the two lines to be joined on display, and the \
backslash will not show. (If you end a line with a backslash and a tab \
or space, it will ''not'' be joined with the next line, and the backslash \
will be printed.)
----
++ Inline Formatting
|| {{```''italic text''```}} || ''italic text'' ||
|| {{```'''bold text'''```}} || '''bold text''' ||
|| {{```'''''italic and bold'''''```}} || '''''italic and bold''''' ||
|| {{```//emphasis//```}} || //emphasis// ||
|| {{```**strong**```}} || **strong** ||
|| {{```//**emphasis and strong**//```}} || //**emphasis and strong**// ||
|| {{```**//strong and emphasis//**```}} || **//strong and emphasis//** ||
|| {{```{{teletype text}}```}} || {{teletype text}} ||
|| {{<```php:function()```>}} || <php:function()> ||
|| {{```@@--- delete text +++ insert text @@```}} || @@--- delete text +++ insert text @@ ||
|| {{```@@--- delete only @@```}} || @@--- delete only @@ ||
|| {{```@@+++ insert only @@```}} || @@+++ insert only @@ ||
|| {{```super ^^1^^ script```}} || super ^^1^^ script ||
----
++ Literal Text
If you don't want Text_Wiki to parse some text, enclose it in 3 backticks (not 3 single-quotes).
<code>
This '''text''' gets {{parsed}}.
```This '''text''' does not get {{parsed}}.```
</code>
This '''text''' gets {{parsed}}.
```This '''text''' does not get {{parsed}}.```
----
++ Headings
You can make various levels of heading by putting \
equals-signs before and after the text (all on its \
own line):
<code>
+++ Level 3 Heading
++++ Level 4 Heading
+++++ Level 5 Heading
++++++ Level 6 Heading
</code>
+++ Level 3 Heading
++++ Level 4 Heading
+++++ Level 5 Heading
++++++ Level 6 Heading
----
++ Table of Contents
To create a list of every heading, with a link to that heading, put a table of contents tag on its own line.
<code>
%%TOC%%
</code>
----
++ Horizontal Rules
Use four dashes ({{```----```}}) to create a horizontal rule.
----
++ Lists
+++ Bullet Lists
You can create bullet lists by starting a paragraph with one or \
more asterisks.
<code>
* Bullet one
* Sub-bullet
</code>
* Bullet one
* Sub-bullet
+++ Numbered Lists
Similarly, you can create numbered lists by starting a paragraph \
with one or more hashes.
<code>
# Numero uno
# Number two
# Sub-item
</code>
# Numero uno
# Number two
# Sub-item
+++ Mixing Bullet and Number List Items
You can mix and match bullet and number lists:
<code>
# Number one
* Bullet
* Bullet
# Number two
* Bullet
* Bullet
* Sub-bullet
# Sub-sub-number
# Sub-sub-number
# Number three
* Bullet
* Bullet
</code>
# Number one
* Bullet
* Bullet
# Number two
* Bullet
* Bullet
* Sub-bullet
# Sub-sub-number
# Sub-sub-number
# Number three
* Bullet
* Bullet
+++ Definition Lists
You can create a definition (description) list with the following syntax:
<code>
:Item 1: Something
:Item 2: Something else
</code>
:Item 1: Something
:Item 2: Something else
----
++ Block Quotes
You can mark a blockquote by starting a line with one or more '>' \
characters, followed by a space and the text to be quoted.
<code>
This is normal text here.
> Indent me! The quick brown fox jumps over the lazy dog. \
Now this the time for all good men to come to the aid of \
their country. Notice how we can continue the block-quote \
in the same "paragraph" by using a backslash at the end of \
the line.
>
> Another block, leading to...
>> Second level of indenting. This second is indented even \
more than the previous one.
Back to normal text.
</code>
This is normal text here.
> Indent me! The quick brown fox jumps over the lazy dog. \
Now this the time for all good men to come to the aid of \
their country. Notice how we can continue the block-quote \
in the same "paragraph" by using a backslash at the end of \
the line.
>
> Another block, leading to...
>> Second level of indenting. This second is indented even \
more than the previous one.
Back to normal text.
----
++ Links and Images
+++ Wiki Links
SmashWordsTogether to create a page link.
You can force a WikiPage name '''not''' to be clickable by putting \
an exclamation mark in front of it.
<code>
WikiPage !WikiPage
</code>
WikiPage !WikiPage
(Note: existing wiki pages must be in the Text_Wiki {{pages}} option array, \
and the {{view_url}} option must be set for the linking to work.)
+++ Free Links
Freelinks are "non-standard" Wiki links.
* You can refer to named anchors within pages like this: \
{{```((WikiPage#NamedAnchor))```}} becomes ((WikiPage#NamedAnchor)).
* You can create nice-looking links from WordsSmashedTogether like this: \
{{```((WordsSmashedTogether|Nice Link))```}} becomes \
((WordsSmashedTogether|Nice Link)).
* Refer to named anchors within nice-looking links like this: \
{{```((WikiPage|Nice Link#Anchor))```}} becomes \
((WikiPage|Nice Link#Anchor)).
* You can also create links that aren't WordsSmashedTogether \
(i.e., that have spaces) like this: {{```((free links))```}} \
becomes ((free links)).
(Note: existing wiki pages must be in the Text_Wiki {{pages}} option array, \
and the {{view_url}} option must be set for the linking to work.)
+++ Interwiki Links
Interwiki links are links to pages on other Wiki sites. \
Type the {{```SiteName:PageName```}} like this:
* MeatBall:RecentChanges
* Advogato:proj/WikkiTikkiTavi
* Wiki:WorseIsBetter
(Note: the interwiki site must be in the Text_Wiki {{interwiki}} option array.)
+++ URLs
Create a remote link simply by typing its URL: http://ciaweb.net.
If you like, enclose it in brackets to create a numbered reference \
and avoid cluttering the page; {{```[http://ciaweb.net/free/]```}} becomes [http://ciaweb.net/free/].
Or you can have a described-reference instead of a numbered reference:
<code>
[http://pear.php.net PEAR]
</code>
[http://pear.php.net PEAR]
+++ Images
You can put a picture in a page by typing the URL to the picture \
(it must end in gif, jpg, or png).
<code>
http://c2.com/sig/wiki.gif
</code>
http://c2.com/sig/wiki.gif
You can use the described-reference URL markup to give the image an ALT tag:
<code>
[http://www.netropolisusa.biz/billthemarmet/MT/index/images/sunset_07_10_03.jpg Sunset]
</code>
[http://www.netropolisusa.biz/billthemarmet/MT/index/images/sunset_07_10_03.jpg Sunset]
----
++ Code Blocks
Create code blocks by using {{<code>...</code>}} tags (each on its own line).
<code>
This is an example code block!
</code>
To create PHP blocks that get automatically colorized when you use PHP tags, \
simply surround the code with {{<php>...</php>}} tags (the tags themselves \
should each be on their own lines, and no need for the {{<?php ... ?>}} tags).
<code>
<php>
// Set up the wiki options
$options = array();
$options['view_url'] = "index.php?page=";
// load the text for the requested page
$text = implode('', file($page . '.wiki.txt'));
// create a Wiki objext with the loaded options
$wiki = new Text_Wiki($options);
// transform the wiki text.
echo $wiki->transform($text);
</php>
</code>
<php>
// Set up the wiki options
$options = array();
$options['view_url'] = "index.php?page=";
// load the text for the requested page
$text = implode('', file($page . '.wiki.txt'));
// create a Wiki objext with the loaded options
$wiki = new Text_Wiki($options);
// transform the wiki text.
echo $wiki->transform($text);
</php>
----
++ Tables
You can create tables using pairs of vertical bars:
<code>
|| cell one || cell two ||
|||| big ol' line ||
|| cell four || cell five ||
|| cell six || here's a very long cell ||
</code>
|| cell one || cell two ||
|||| big ol' line ||
|| cell four || cell five ||
|| cell six || here's a very long cell ||
<code>
|| lines must start and end || with double vertical bars || nothing ||
|| cells are separated by || double vertical bars || nothing ||
|||| you can span multiple columns by || starting each cell ||
|| with extra cell |||| separators ||
|||||| but perhaps an example is the easiest way to see ||
</code>
|| lines must start and end || with double vertical bars || nothing ||
|| cells are separated by || double vertical bars || nothing ||
|||| you can span multiple columns by || starting each cell ||
|| with extra cell |||| separators ||
|||||| but perhaps an example is the easiest way to see ||
--- NEW FILE: SmashWordsTogether.wiki.txt ---
Smash words together to create a link.
--- NEW FILE: TextWikiProposal.wiki.txt ---
+ Text_Wiki Proposal
This is an updated version of the proposal to PEAR group for {{Text_Wiki}} by [mailto:pm...@ci... Paul M. Jones].
%%TOC%%
----
++ Overview
Most Wiki projects use their own internal, specialized parsing and rendering engines to transform source Wiki text to HTML. The rule structures of different Wiki implementations are usually incompatible, leading developers to write their own engine to parse and render their own specialized Wiki markup. This makes it difficult to extract and compare rule structure, as well as making it troublesome to add/modify/delete existing markup rules. In addition, this makes it near-impossible to "drop in" Wiki text transformation processes to a nominally non-Wiki project.
To solve the rule-modification and drop-in problems noted above, {{Text_Wiki}} abstracts the process of displaying Wiki-formatted text by using an object-oriented rule structure for parsing and rendering.
A default set of parsing and rendering rule classes is provided with {{Text_Wiki}}; they serve to implement basic Wiki transformation into XHTML, and provide useful, well-commented examples of how to write a Wiki transformation rule.
In addition, individual parsing and rendering rules can be added, modified, and removed with a user-defined rules directory. Depending on the rendering method for a rule, source Wiki text may be transformed into XHTML, Latex, PDF, RTF, and so on.
The properties of a {{Text_Wiki}} object determine...
* which rules are applied to the source Wiki text (and in what order),
* what the !WikiWeb URLs are for viewing and editing pages,
* Interwiki mappings,
* which pages exist in the !WikiWeb,
* and much more.
{{Text_Wiki}} does not implement a full !WikiWikiWeb; it only handles the transformation of Wiki source text to an output format.
----
++ History and Research
Please note that {{Text_Wiki}} was pre-proposed earlier this year with some positive response[http://marc.theaimsgroup.com/?t=105838978200001&r=1&w=2] and that the call for votes is complete.[http://marc.theaimsgroup.com/?t=106994688000001&r=1&w=2]
Primary research for {{Text_Wiki}} was based on two open-source Wiki projects, [http://tavi.sourceforge.net/ WikkiTikkiTavi] and [http://www.develnet.org/ coWiki]. Other Wiki engines and rule sets were also used in research, but these two provide sufficient examples for Wiki implementation.
----
++ What Is Wiki?
A !WikiWikiWeb (a "Wiki") is a web-based collaboration tool in which any user can edit any page on the site.
To quote C2: "Wiki is a composition system, it's a discussion medium, it's a repository, it's a mail system, it's a chat room, and it's a tool for collaboration."[http://c2.com/cgi/wiki]
+++ Wiki Markup Is Easy To Understand...
Wikis allow rich text markup and automatic page linking.
Because Wiki content is entered as plain text in a web environment, Wikis do not generally use HTML for rich text markup; instead, they use structured text to mark the elements of a page.
For example, in HTML, one would mark a heading using {{<hN>...</hN>}} tags.
<code>
<html>
<h3>This is a heading.</h3>
<p>This is not.</p>
</html>
</code>
To mark a heading in a Wiki, you put the heading on its own line and prefix it with a number of plus-signs. Thus, the corresponding Wiki markup for the above example would look something like this:
<code>
+++ This is a heading.
This is not.
</code>
There are different structure rules for different markup elements. For example, bold text might be enclosed in a paired sets of three single quotes, teletype text is set off my matched pairs of 2 curly braces, lists are noted by starting the like with a hash or a star, and so on.
Wikis also automate the creation and linking of pages. In a Wiki, page names are made of WordsSmashedTogether; the Wiki sees WordsSmashedTogether on a page and creates a link to the corresponding page in the Wiki. If the page exists on the Wiki, the page name itself becomes a link; if the page does not exist, a suffix is added to the page name, usually a question mark, and that suffix is linked to the "create a new page" URL.
This means that in order to translate Wiki-formatted structured text (from the source) to HTML (for display), it is necessary to do a find-and-replace on the text, looking for text lines that match the Wiki structured text rules, and convert them to HTML for display. Most Wiki engines parse-and-render within a single class, or with a series of functions within a single include file.
+++ ...But It's Not Standardized...
The problem with Wiki markup is that it is not standardized. Different Wiki engines use different rule structures. In general, Wiki implementors want the source text to be make sense when read by humans, and also be translatable to HTML. What "makes sense" to one developer or community might not make sense to another.
By way of example, let's take a look at headings. In HTML, a heading is always marked the same way. In different Wikis, headings are not always the same. In !WikkiTikkiTavi, a heading-2 looks like this:
<code>
== My Heading ==
</code>
But in coWiki, it looks like this:
<code>
++ My Heading
</code>
And in another wiki, it might look like this:
<code>
---- My Heading
</code>
(Why four dashes instead of two? Because the implementor decided that a heading-1 should use six dashes as the most-important, and work down to a heading-6 that uses one dash as the least-important.)
It's even worse when we get to bold, italics, and so on.
* Some Wikis use {{```''italic''```}}, others use {{```//italic//```}}, and others use {{```_italic_```}}.
* Some Wikis implement partial HTML support so you can embed tables, others use a double-pipe markup style to mark cells.
* Some Wikis implement XML-ish tags to mark elements.
* Some Wikis implement plugins or macros to embed custom behaviors into Wiki pages.
+++ ...And It's Hard To Share.
But what some Wikis do, others do not. This means that if you want Wiki implementation "A" to support a rule or behavior from Wiki implementation "B", it becomes difficult or impossible, because the different implementations use different parsing and rendering routines that apply their rule structures in different ways.
Not only that, but the parsing and rendering routines generally depend on the whole remainder of the Wiki implementation. This means the Wiki transformation engine exists within a full !WikiWikiWeb system that handles page creation, versioning, storage, and linking, sometimes along with {{diff()}} functions to see the differences between page edits.
----
++ Text_Wiki Makes It Easy To Share
{{Text_Wiki}} solves the problem of sharing rules and behaviors by using a unified parsing and rendering mechanism with an object-oriented system of rules for transforming Wiki markup elements.
Each Wiki element gets its own rule class. The rule class handles its own parsing and rendering within the context of the primary {{Text_Wiki}} object, but has full access to the primary {{Text_Wiki}} object properties (the source text, the elements that have already been parsed, and so on).
This means that you can add, change, and remove rules for any specific Wiki markup set you happen to like. It also means that if you see a Wiki behavior that you like, you can easily write a new rule that mimics the behavior and plug it into the {{Text_Wiki}} engine without rewriting the parser or renderer.
Thus, instead of implementing a full !WikiWikiWeb system, {{Text_Wiki}} only deals with the transformation of Wiki source text to an output format. (Incidentally, it needs to know whether a page exists within a !WikiWeb, but that is abstracted and does not depend on any specific storage or retrieval system.)
+++ How Does This Work?
In general, {{Text_Wiki}} uses a replace-with-token methodology to mark source text matching a Wiki rule. Any source text matching a rule (usually found through a regular expression) is replaced with a pair of delimiters surrounding a token number, and a matching token number is entered into the {{Text_Wiki}} {{$_tokens}} array property. Any optional information about the matching text, and sometimes the matching text itself, is stored in the token entry. After parsing, the tokens are rendered into a target format depending on the rule's render() method.
As a side-benefit, this means that once the source text has been parsed and tokenized, the combination of the source text and replacement tokens allows you to target any output format, not just XHTML. If a rule supports it, that rule can render a token into Latex, PDF, RTF, and so on.
+++ Examples
The best example of {{Text_Wiki}} is the {{Text_Wiki}} sample page, included in the package documentation. After you use PEAR to install {{Text_Wiki}}, look in the docs/ directory. The index.php file show how to instantiate a {{Text_Wiki}} object with a set of custom options, and Sample.wiki.txt shows how to write up Wiki source text. Finally, open index.php in your browser to see the Wiki source text transformed into HTML.
----
++ Download the Package
http://pear.php.net/package/Text_Wiki
+++ Known Issues
Need to create full documentation, including how to write a rule.
{{Text_Wiki}} should return {{PEAR_Error}} objects and error codes, not echo errors to output.
Should add {{renderLatex()}} method for all default rules (from !WikkiTikkiTavi?)
--- NEW FILE: TokenRuleKeys.wiki.txt ---
+ Token Rule Keys
|| '''Rule Name''' || '''Description''' || '''Options''' ||
|| {{blockquote}} || Block-quoted text. || {{type:[start|end] }} ||
|| {{bold}} || Bold text. || {{type:[start|end]}} ||
|| {{code}} || A block of generic computer code. || {{text}} ||
|| {{deflist}} || Definition list element. || {{type:[list|term|narr]_[start|end]}} ||
|| {{delimiter}} || An existing delimiter. || - ||
|| {{emphasis}} || Emphasized (usually italic) text. || {{type:[start|end]}} ||
|| {{freelink}} || A local !WikiPage reference in free link format. || {{page}}, {{text}}, {{anchor}} ||
|| {{heading}} || A heading. || {{type:[start|end], level, text}} ||
|| {{horiz}} || A horizontal rule. || - ||
|| {{html}} || A block of HTML text to be displayed as-is. || {{text}} ||
|| {{interwiki}} || An !InterWiki reference. || {{site}}, {{page}} ||
|| {{italic}} || Italic text. || {{type:[start|end]}} ||
|| {{list}} || Bullet or number list elements. || {{type:[bullet|number|item]_[start|end], level, count}} ||
|| {{newline}} || A new line or line break. || - ||
|| {{phpcode}} || A block of PHP code to be colorized. || {{text}} ||
|| {{phplookup}} || A function name to link to at php.net || {{text}} ||
|| {{raw}} || Raw or plain text to be displayed as-is. || {{text}} ||
|| {{strong}} || Strong (usually bold) text. || {{type:[start|end]}} ||
|| {{superscript}} || Superscript text. || {{type:[start|end]}} ||
|| {{table}} || Table elements. || {{type:[table|row|cell]_[start|end], colspan}} ||
|| {{tt}} || Teletype (monospaced) text. || {{type:[start|end]}} ||
|| {{url}} || A page URL. || {{type:[inline|footnote|descr]}}, {{href}}, {{text}} ||
|| {{wikilink}} || A local !WikiPage reference. || {{page}}, {{anchor}} ||
|| {{toc}} || Table of contents. || {{type:[list_start|list_end|item_start|item_end|target], level, count}} ||
++ Tokens Entry Format
Simple format (no options).
<code>
$_tokens[] = Array
(
[0] => 'rule_name'
[1] => array
(
)
)
</code>
Complex format (with options).
<code>
$_tokens[] = Array
(
[0] => 'rule_name'
[1] => Array
(
['opt0'] => 'value 0'
['opt1'] => 'value 1'
...
['optN'] => 'value N'
)
)
</code>
--- NEW FILE: WikiPage.wiki.txt ---
A generic blank Wiki page.
--- NEW FILE: WordsSmashedTogether.wiki.txt ---
Smash words together to create a link.
--- NEW FILE: free links.wiki.txt ---
A "free link" Wiki page.
--- NEW FILE: index.php ---
<?php
error_reporting(E_ALL);
require_once 'Text/Wiki.php';
/**
*
* Gets microtime; for timing how long it takes to process code.
*
*/
function getmicrotime()
{
list($usec, $sec) = explode(" ",microtime());
return ((float)$usec + (float)$sec);
}
// Set up the wiki options
$options = array();
$options['view_url'] = "index.php?page=";
// Get the list of existing wiki pages, based on the .wiki.txt
// files in the current directory.
$options['pages'] = array();
$dir = opendir(dirname(__FILE__));
while ($file = readdir($dir)) {
if (substr($file, -9) == '.wiki.txt') {
$options['pages'][] = substr($file, 0, -9);
}
}
closedir($dir);
// what page is being requested?
if (isset($_GET['page'])) {
$page = $_GET['page'];
} else {
$page = 'HomePage';
}
// load the text for the requested page
$text = implode('', file($page . '.wiki.txt'));
// create a Wiki objext with the loaded options
$wiki =& new Text_Wiki($options);
// time the operation, and transform the wiki text.
$before = getMicroTime();
$output = $wiki->transform($text);
$after = getMicroTime();
$time = (float)$after - (float)$before;
// output the page!
?>
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>Text_Wiki::<?php echo $page ?></title>
<link rel="stylesheet" href="stylesheet.css" type="text/css" />
</head>
<body>
<?php echo $output ?>
<?php echo "<hr /><p>Transformed in $time seconds.</p>" ?>
</body>
</html>
--- NEW FILE: stylesheet.css ---
body, p, br, th, td {
font-family: "Verdana", "Arial", "Geneva";
font-size: 12px;
}
th {
font-weight: bold;
background: black;
color: white;
}
h1 {
font-size: 30px;
font-family: "Arial Narrow", "N Helvectica Narrow", "Tahoma";
font-weight: bold;
}
h2 {
font-size: 24px;
font-family: "Arial Narrow", "N Helvectica Narrow", "Tahoma";
font-weight: bold;
}
h3 {
font-size: 18px;
font-family: "Arial Narrow", "N Helvectica Narrow", "Tahoma";
font-weight: bold;
}
h4 {
font-size: 16px;
font-family: "Arial Narrow", "N Helvectica Narrow", "Tahoma";
font-weight: bold;
}
h5 {
font-size: 14px;
font-family: "Arial Narrow", "N Helvectica Narrow", "Tahoma";
font-weight: bold;
}
h6 {
font-size: 12px;
font-family: "Arial Narrow", "N Helvectica Narrow", "Tahoma";
font-weight: bold;
}
a:link {
color: blue;
text-decoration: none;
}
a:visited {
color: blue;
text-decoration: none;
}
a:hover {
color: red;
text-decoration: underline;
}
pre {
border: 1px dashed #003366;
background: #eeeeee;
padding: 6px;
font-family: Profont, Monaco, Courier, "Andale Mono", monospace;
}
|