[Sommaire] [Imprimer]

   1  + Text_Wiki
   2  
   3  %%TOC%%
   4  
   5  ++ Overview and Background
   6  
   7  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.
   8  
   9  The {{Text_Wiki}} package allows you to transform text structured using Wiki rules into any defined target output format. For example, you can convert...
  10  
  11  * Tavi-style Wiki text into XHTML
  12  * Original C2-style Wiki text into XML
  13  * !MeatBall style Wiki text into !LaTeX
  14  * Any other Wiki markup rules into any other format (provided it's programmed properly ;-)
  15  
  16  {{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:
  17  
  18  * A constructor that links back to the "master" Text_Wiki class, which the source text as well as any optional confugration parameters
  19  * A parse() method that looks through the source text for strings that match a regular expression
  20  * 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)
  21  * A render() method that replaces a saved token with output for a specific target format (e.g., XHTML or !LaTeX).
  22  
  23  {{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.
  24  
  25  Also see these pages for more information:
  26  
  27  * SamplePage -- for a full list of default markup rules
  28  * TokenRuleKeys -- for a list of the tokens keys generated by different rules
  29  * TextWikiProposal -- a modified version of the initial Text_Wiki proposal to PEAR
  30  
  31  ++ What Text_Wiki Does Not Do
  32  
  33  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).
  34  
  35  ++ Using Text_Wiki
  36  
  37  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.
  38  
  39  <php>
  40      
  41      // require the Text_Wiki class and create an instance of a new wiki
  42      // parse-and-render object
  43      require_once 'Text/Wiki.php';
  44      $wiki = new Text_Wiki();
  45      
  46      // load up some source text
  47      $text = file_get_contents('sample.wiki.txt');
  48      
  49      // transform the text using the default rules for parsing and rendering.
  50      // the extra \n newlines seem to help with some parsing rules.
  51      echo $wiki->transform("\n" . $text . "\n");
  52      
  53  </php>
  54  
  55  
  56  
  57  ++ Text_Wiki Options
  58  
  59  When you create an instance of Text_Wiki, you can pass a set of options as an associative array. 
  60  
  61  The array keys for the options are:
  62  
  63  || '''option key''' || '''variable type''' || '''description''' ||
  64  || {{delim}}        || string              || the source text delimiter for tokens ||
  65  || {{interwiki}}    || array               || interwiki site names and URLs ||
  66  || {{new_text}}     || string              || link-text for new pages ||
  67  || {{new_url}}      || string              || URL for new pages ||
  68  || {{pages}}        || array               || list of pages existing in the wiki ||
  69  || {{rules}}        || array               || the list of rules to be applied to source text ||
  70  || {{view_url}}     || string              || URL for viewing pages in the wiki ||
  71  
  72  For example:
  73  
  74  <php>
  75      // the list of rules, and in which order, to use when
  76      // transforming structured text; the key is the name to use for
  77      // identifying tokens for the rule, and the value is the file
  78      // name of the rule class.
  79      $rules = array(
  80          'prefilter'   => 'Text/Wiki/Rule/prefilter.php',
  81          'delimiter'   => 'Text/Wiki/Rule/delimiter.php',
  82          'code'        => 'Text/Wiki/Rule/code.php',
  83          'phpcode'     => 'Text/Wiki/Rule/phpcode.php',
  84          'html'        => 'Text/Wiki/Rule/html.php',
  85          'heading'     => 'Text/Wiki/Rule/heading.php',
  86          'horiz'       => 'Text/Wiki/Rule/horiz.php',
  87          'blockquote'  => 'Text/Wiki/Rule/blockquote.php',
  88          'deflist'     => 'Text/Wiki/Rule/deflist.php',
  89          'table'       => 'Text/Wiki/Rule/table.php',
  90          'list'        => 'Text/Wiki/Rule/list.php',
  91          'toc'         => 'Text/Wiki/Rule/toc.php',
  92          'paragraph'   => 'Text/Wiki/Rule/paragraph.php',
  93          'raw'         => 'Text/Wiki/Rule/raw.php',
  94          'phplookup'   => 'Text/Wiki/Rule/phplookup.php',
  95          'url'         => 'Text/Wiki/Rule/url.php',
  96          'interwiki'   => 'Text/Wiki/Rule/interwiki.php',
  97          'freelink'    => 'Text/Wiki/Rule/freelink.php',
  98          'wikilink'    => 'Text/Wiki/Rule/wikilink.php',
  99          'strong'      => 'Text/Wiki/Rule/strong.php',
 100          'bold'        => 'Text/Wiki/Rule/bold.php',
 101          'emphasis'    => 'Text/Wiki/Rule/emphasis.php',
 102          'italic'      => 'Text/Wiki/Rule/italic.php',
 103          'tt'          => 'Text/Wiki/Rule/tt.php',
 104          'superscript' => 'Text/Wiki/Rule/superscript.php',
 105          'revise'      => 'Text/Wiki/Rule/revise.php',
 106          'entities'    => 'Text/Wiki/Rule/entities.php',
 107          'tighten'     => 'Text/Wiki/Rule/tighten.php'
 108      );
 109      
 110      // the list of InterWiki names and URLs
 111      $interwiki = array(
 112          'MeatBall' => 'http://www.usemod.com/cgi-bin/mb.pl?',
 113          'Advogato' => 'http://advogato.org/',
 114          'Wiki'     => 'http://c2.com/cgi/wiki?'
 115      );
 116      
 117      // the URL used to view local WikiWeb pages
 118      $view_url = "http://example.com/wiki.php?page=";
 119      
 120      // create a Text_Wiki options array
 121      $options = array(
 122          'rules'     => $rules,
 123          'interwiki' => $interwiki,
 124          'view_url'  => $view_url
 125      );
 126      
 127      // instantiate a Text_Wiki object with the options
 128      $wiki =& new Text_Wiki($options);
 129  </php>
 130  
 131  
 132  
 133  +++ {{delim}}
 134  
 135  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.
 136  
 137  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.
 138  
 139  For example:
 140  
 141  <php>
 142      // use a nullchar delimiter
 143      $options['delim'] = '\x00');
 144  </php>
 145  
 146  
 147  
 148  +++ {{interwiki}}
 149  
 150  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.
 151  
 152  <php>
 153      // name and link to the MeatBall Wiki
 154      $options['interwiki'] = array(
 155          'MeatBall' => 'http://www.usemod.com/cgi-bin/mb.pl?'
 156      );
 157  </php>
 158  
 159  
 160  
 161  
 162  +++ {{new_text}}
 163  
 164  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.
 165  
 166  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.
 167  
 168  See also the {{new_url}} option.
 169  
 170  <php>
 171      // use a question mark and a space
 172      $options['new_text'] = '? ';
 173      
 174      // use an image
 175      $options['new_text'] = '<img src="http://example.com/newpage.gif />';
 176  </php>
 177  
 178  
 179  
 180  +++ {{new_url}}
 181  
 182  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.
 183  
 184  The {{new_url}} specifies the URL to the application-specific page creation utility.
 185  
 186  See also the {{new_text}} option.
 187  
 188  <php>
 189      // link to the new-page script
 190      $options['new_url']  = 'http://example.com/newpage.php?page=';
 191  </php>
 192  
 193  
 194  +++ {{pages}}
 195  
 196  The {{pages}} option is a sequential array where each element is the name of page in the Wiki.  See also the {{view_url}} option.
 197  
 198  <php>
 199      // only three pages in this wiki
 200      $options['pages'] = array(
 201          'HomePage',
 202          'SamplePage',
 203          'TokenRuleKeys'
 204      )
 205  </php>
 206  
 207  
 208  +++ {{rules}}
 209  
 210  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.)
 211  
 212  <php>
 213      $options['rules'] = array(
 214          'prefilter'   => 'Text/Wiki/Rule/prefilter.php',
 215          'delimiter'   => 'Text/Wiki/Rule/delimiter.php',
 216          'code'        => 'Text/Wiki/Rule/code.php',
 217          'phpcode'     => 'Text/Wiki/Rule/phpcode.php',
 218          'html'        => 'Text/Wiki/Rule/html.php',
 219          'heading'     => 'Text/Wiki/Rule/heading.php',
 220          'horiz'       => 'Text/Wiki/Rule/horiz.php',
 221          'blockquote'  => 'Text/Wiki/Rule/blockquote.php',
 222          'deflist'     => 'Text/Wiki/Rule/deflist.php',
 223          'table'       => 'Text/Wiki/Rule/table.php',
 224          'list'        => 'Text/Wiki/Rule/list.php',
 225          'toc'         => 'Text/Wiki/Rule/toc.php',
 226          'paragraph'   => 'Text/Wiki/Rule/paragraph.php',
 227          'raw'         => 'Text/Wiki/Rule/raw.php',
 228          'phplookup'   => 'Text/Wiki/Rule/phplookup.php',
 229          'url'         => 'Text/Wiki/Rule/url.php',
 230          'interwiki'   => 'Text/Wiki/Rule/interwiki.php',
 231          'freelink'    => 'Text/Wiki/Rule/freelink.php',
 232          'wikilink'    => 'Text/Wiki/Rule/wikilink.php',
 233          'strong'      => 'Text/Wiki/Rule/strong.php',
 234          'bold'        => 'Text/Wiki/Rule/bold.php',
 235          'emphasis'    => 'Text/Wiki/Rule/emphasis.php',
 236          'italic'      => 'Text/Wiki/Rule/italic.php',
 237          'tt'          => 'Text/Wiki/Rule/tt.php',
 238          'superscript' => 'Text/Wiki/Rule/superscript.php',
 239          'revise'      => 'Text/Wiki/Rule/revise.php',
 240          'entities'    => 'Text/Wiki/Rule/entities.php',
 241          'tighten'     => 'Text/Wiki/Rule/tighten.php'
 242      );
 243  </php>
 244  
 245  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:
 246  
 247  <php>
 248      // [snip] set up $options
 249      $wiki =& new Text_Wiki($options);
 250      
 251      // replace the 'wikilink' default rule
 252      $wiki->rules['wikilink'] = '/path/to/my/rules/my_wikilink.php';
 253  </php>
 254  
 255  
 256  +++ {{view_url}}
 257  
 258  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.
 259  
 260  <php>
 261      // link to the page-viewing script
 262      $options['view_url'] = 'http://example.com/wiki.php?page=';
 263  </php>