how to use Pear Text_wiki

Question

The docs on the pear website link to a site that cannot be accessed. Does anyone know a site, article, or book that would explain how to use the Text_wiki package?

Answer 1

@mario's answer is accurate, albeit brief. I was frustrated by the lack of "let's get you started quickly" documentation too and spent some time communing with the source (which admittedly is never a bad thing). Here's some more background information for future potential users of the Text_Wiki PEAR package:

To use the PEAR package:

• Install it with something like pear install Text_Wiki

• Alternatively, you can install any of the sub-packages directly, such as Mediawiki: pear install Text_Wiki_Mediawiki

• Once the PEAR package is installed, you can require_once 'Text/Wiki/Mediawiki.php'; in your PHP file, assuming PHP and PEAR are set up correctly. (See also: PEAR Troubleshooting Tips)

From there you can pick up where mario started. Here's a bit more detail to help you out:

• This package uses one class for each "rule" (like for Paragraphs, Headers, Wikilinks, Tables, ...).

• The rules are organized as individual PHP class files in your PEAR directory and split into "Parse" classes that match parts of your wikitext input and "Render" classes that format the matched wikitext into an output format like plain text or XHTML.

• You can find your PEAR directory using pear config-get php_dir. For example, mine is /usr/share/php

• Installed PEAR packages are in subfolders matching the package name, so on my machine, "Text_Wiki_Mediawiki" is in /usr/share/php/Text/Wiki/Mediawiki

• For a given output type (like "Xhtml'), each Render rule has its own configuration options. (Look in Text/Wiki/Render/Xhtml/Wikilink.php for Wikilink rule options.) These options must be set with the SetRenderConf() method.

• SetRenderConf() takes the following arguments:

  • The name of the output type, usually 'xhtml'
  • The name of the Rule you want to adjust, which will match the file name. 'Wikilink' for example.
  • The name of the option from that rule that you want to set.
  • The value to assign to that option.

• You have to read each rule's source code to know what options are available for it.

• You can control which rules to use and what order to call them by passing an array or strings with rule names into the constructor.

<?php
require_once 'Text/Wiki/Mediawiki.php';

// If you only wanted ==Heading==s, <P>aragraphs and 
// [[Wikilink]]s in your output:
//$rules = array('Heading', 'Paragraph', 'Wikilink');
//$wiki = new Text_Wiki_Mediawiki($rules);


// Create a new Text_Wiki instance with default rules:
$wiki = new Text_Wiki_Mediawiki();

// When rendering XHTML, make sure "internal" wiki links 
// point to a specific base URL.
$wiki->setRenderConf('xhtml', 'Wikilink', 'view_url', 
  'http://your.wikibaseurl.com/wiki/'); 

// Turn off fake "page exists?" checking. 
// This makes every "internal" link point to an "existing" wiki page 
// instead of a "page doesn't exist, do you want to create it?" page.
$wiki->setRenderConf('xhtml', 'Wikilink', 'pages', false);  

// Turn off opening external links in a new window. 
$wiki->setRenderConf('xhtml', 'Url', 'target', false);  

// With all of your options set, transform source text 
// into a destination format using the "Xhtml" renderers.
print $wiki->transform("==Some wiki text==", 'Xhtml');

These additional points should get you started much faster by helping you know where to look to find the settings that can be adjusted.