7b6f5f1a166e941597df36f41cf10abf7e2e3f56
[moodle.git] / mod / wiki / ewiki / README
2 ErfurtWiki - a fast, user-friendly, highly configurable Wiki engine in PHP
3 ==========================================================================
6 README
7 ������
8 This is the documentation for ewiki. I tries to describe nearly everything,
9 but therefore has now grown to long to be read at once. However it is often
10 sufficient to just read the first few paragraphs to set it up (plugins can be
11 activated at any later time). If you have the Wiki running, then you can also
12 read this file in hypertext format.
15         1  What is this?
16       1.1  Why "ErfurtWiki"?
17       1.2  WikiAlternatives
18       1.3  Authors
19       1.4  Project pages
20       1.5  Obtaining support
21       1.6  License
22       1.7  Known Bugs
24         2  HowTo
25       2.1  Integration with yoursite.php
26     2.1.1  Creating a "config.php"
27     2.1.2  Generation of a "monsterwiki.php" script
28     2.1.3  What to do if images don't work
29       2.2  Supplying the WikiPageName
30     2.2.1  mod_rewrite or PATH_INFO
31     2.2.2  use with the 404 trick
32       2.3  Security considerations
33     2.3.1  PHP settings (register_globals)
34     2.3.2  _protected_mode
35       2.4  simple usage restrictions via wrappers
36       2.5  PhpWiki compatibility
37     2.5.1  Transition from another WikiWare
38       2.6  Idea Collection
39     2.6.1  Multiple Wikis / InterWiki feature abuse
41         3  Internals
42       3.1  the ewiki_ functions
43       3.2  $GLOBALS pollution
44       3.3  the EWIKI_ constants
45       3.4  $ewiki_config array
46       3.5  internal coding explained
47     3.5.1  how ewiki operates
48     3.5.2  used variables
50         4  Tweaking
51       4.1  Using the wiki source transformation only
52       4.2  Customizing ewiki_format()
53       4.3  Customization using CSS
54     4.3.1  user style classes in pages
55     4.3.2  rendered page content
56     4.3.3  pages enclosed in style classes
57     4.3.4  plugin output styling
59         5  Explanations
60       5.1  Binary and text support
61     5.1.1  Image uploading
62     5.1.2  Image caching
63     5.1.3  Image WikiMarkup
64     5.1.4  binary_store, direct access
65     5.1.5  Arbitrary binary content
66       5.2  $action and $id
67     5.2.1  ewiki URLs
69         6  Everything in one script
70       6.1  database plugins
71     6.1.1  MySQL support
72     6.1.2  plugins/db/flat_files         (IMPORTANT)
73     6.1.3  plugins/db/fast_files
74     6.1.4  plugins/db/any
75     6.1.5  plugins/db/adodb
76     6.1.6  plugins/db/dba
77     6.1.7  plugins/db/phpwiki13
78     6.1.8  plugins/db/binary_store
79       6.2  core enhancements
80     6.2.1  plugins/patchsaving
81     6.2.2  plugins/notify
82     6.2.3  plugins/jump
83     6.2.4  plugins/email_protect
84     6.2.5  plugins/spages (StaticPages)
85     6.2.6  plugins/pluginloader
86     6.2.7  plugins/init
87     6.2.8  plugins/feature/appendonly.php
88     6.2.9  plugins/feature/imgresize_gd.php
89     6.2.A  plugins/feature/imgresize_magick.php
90     6.2.B  plugins/feature/spellcheck.php
91       6.3  action/ plugins
92     6.3.1  plugins/action/diff.php
93     6.3.2  plugins/action/translation.php
94     6.3.3  plugins/action/like_pages.php
95     6.3.4  plugins/action/raw.php
96       6.4  plugins related to hypertext links
97     6.4.1  plugins/linking/tcn
98     6.4.2  plugins/linking/plural
99     6.4.3  plugins/linking/autolinking
100     6.4.4  plugins/linking/link_css
101     6.4.5  plugins/linking/link_icons
102     6.4.6  plugins/linking/link_target_blank
103     6.4.7  plugins/linking/linkexcerpts
104     6.4.8  plugins/linking/linkdatabase
105     6.4.9  plugins/linking/instanturls
106     6.4.A  plugins/linking/titlefix
107     6.4.B  plugins/interwiki/intermap
108       6.5  appearance/ tweaks
109     6.5.1  plugins/appearance/listpages_br
110     6.5.2  plugins/appearance/listpages_ul
111     6.5.3  plugins/appearance/listpages_tbl
112     6.5.4  plugins/appearance/fancy_list_dict
113     6.5.5  plugins/appearance/title_calendar.php
114       6.6  page/ plugins
115     6.6.1  plugins/page/powersearch
116     6.6.2  plugins/page/pageindex
117     6.6.3  plugins/page/wordindex
118     6.6.4  plugins/page/imagegallery
119     6.6.5  plugins/page/aboutplugins
120     6.6.6  plugins/page/orphanedpages
121     6.6.7  plugins/page/wantedpages
122     6.6.8  plugins/page/since_updates
123     6.6.9  plugins/page/textupload
124     6.6.A  plugins/page/wikidump
125     6.6.B  plugins/page/interwikimap
126     6.6.C  plugins/page/hitcounter
127     6.6.D  plugins/page/scandisk
128     6.6.E  plugins/page/wikinews
129     6.6.F  plugins/page/wikiuserlogin
130     6.6.G  plugins/page/randompage
131     6.6.H  plugins/page/fortune
132     6.6.J  plugins/page/ewikilog
133     6.6.J  plugins/page/phpinfo
134     6.6.K  plugins/page/README
135       6.7  markup/ plugins
136     6.7.1  Other WikiWares markup
137     6.7.2  plugins/markup/css
138     6.7.3  plugins/markup/css_singleat
139     6.7.4  plugins/markup/footnotes
140     6.7.5  plugins/markup/asciitbl
141     6.7.6  plugins/markup/complextbl
142     6.7.7  plugins/markup/htmltbl
143     6.7.8  plugins/markup/rescuehtml
144     6.7.9  plugins/markup/rendering_phpwiki12
145     6.7.A  plugins/markup/rendering_null
146       6.8  mpi
147     6.8.1  mpi_backlinks
148     6.8.2  mpi_multimedia
149     6.8.3  mpi_syndicate
150     6.8.4  mpi_insert
151     6.8.5  mpi_localsitemap
152       6.9  visual extensions
153     6.9.1  plugins/aview/backlinks
154     6.9.2  plugins/aview/linktree
155     6.9.3  plugins/aview/toc
156     6.9.4  plugins/aview/posts
157     6.9.5  plugins/aview/threads
158     6.9.6  plugins/aview/subpages
159     6.9.7  plugins/aview/downloads
160     6.9.8  plugins/aview/imgappend
161     6.9.9  plugins/aview/piclogocntrl
162     6.9.A  plugins/aview/aedit_pageimage
163     6.9.B  plugins/aview/control2
164     6.9.C  plugins/aview/aedit_authorname
165     6.9.D  plugins/aview/aedit_deletebutton.js
166       6.A  page filters
167     6.A.1  plugins/filter/f_fixhtml
168     6.A.2  plugins/filter/search_highlight
169     6.A.3  plugins/filter/fun_chef
170     6.A.4  plugins/filter/fun_upsidedown
171     6.A.5  plugins/filter/fun_wella
172     6.A.6  plugins/filter/fun_screamomatic
173     6.A.7  plugins/filter/f_msiepng
174       B.9  BloatWiki extensions
175     6.B.1  plugins/module/calendar
176     6.B.2  plugins/module/downloads
177     6.B.3  plugins/module/tour
178       6.C  utility code
179     6.C.1  plugins/lib/cache
180     6.C.2  plugins/lib/speed
181     6.C.3  plugins/lib/mime_magic
182     6.C.4  plugins/lib/navbar
183     6.C.5  plugins/lib/protmode
184     6.C.6  plugins/lib/save_storevars
185       6.D  admin/ plugins
186     6.D.1  control
187     6.D.2  SearchAndReplace
188     6.D.3  SearchCache
189       6.E  other plugins
190     6.E.1  plugins/debug/
191     6.E.2  plugins/auth/
192     6.E.3  plugins/auth-liveuser/
193       6.F  separate "extra" tarball
195         7  More separate files
196       7.1  Pages in init-pages/
197       7.2  Additional tools/             (IMPORTANT)
198     7.2.1  tools/t_flags
199     7.2.2  tools/t_backup
200     7.2.3  tools/t_restore
201     7.2.4  tools/t_remove
202     7.2.5  tools/t_holes
203     7.2.6  tools/t_textinsert
204     7.2.7  tools/t_transfer
205     7.2.8  tools/t_revert
206     7.2.9  tools/ewikictl
207     7.2.A  tools/wiki2html
208     7.2.B  tools/mkhuge
209     7.2.C  tools/mkpluginmap
210     7.2.D  tools/mkpageplugin
211       7.3  examples/
212     7.3.1  examples/homepage.php
213       7.4  Nice things in fragments/
214     7.4.1  strip_wonderful_slashes.php   (IMPORTANT)
215     7.4.2  strike_register_globals.php
216     7.4.3  404finder.php
217     7.4.4  htaccess
218     7.4.5  binary.php
219       7.5  fragments/funcs/*
220     7.5.1  fragments/funcs/wiki_format.inc
221     7.5.2  fragments/funcs/auth.php
222       7.6  fragments/css/*
223       7.7  fragments/blocks/*
224       7.8  fragments/patches/*
225       7.9  How to deal with tweaked code
227         8  Extension HowTo
228       8.1  the PlugInterface
229       8.2  plugin tasks
230     8.2.1  mpi plugins
231     8.2.2  authentication/permission plugins
232       8.3  writing your own plugin
233       8.4  format_* / rendering plugins
234     8.4.1  ewiki_format() internals
235     8.4.2  the format_ plugin hooks
236     8.4.3  $iii[] and $ooo[] block flags
244   -------------------------------------------------------------------- 1 --
248 What is this?
249 �������������
250 This is a WikiWikiWeb engine implemented in the PHP web scripting
251 language. A WikiWiki is a web site which can be edited by everybody
252 who visits it (most commonly without requiring that user to register
253 before).
255 It should allow easy integration into an existing web site (portal
256 or homepage / CMS-like software), as it is more a library and does
257 not output a full .html page but instead just the formatted wiki
258 text for inclusion in your pages` body/content area.
262 Why "ErfurtWiki"?
263 �����������������
264 My home town (Btw, Erfurt is next to Weimar.de) and really that's
265 just a name (you're allowed to rename, extend it and to finally
266 ship it GPLifyed). You'll soon see the internal name is "ewiki",
267 and it is also sometimes called 'EmbeddableWiki'.
270 If you asked - Why you should I use it?
272  - It is contained within a single file. It does not require 20 other
273    files to lie around between your own scripts.
275  - It does not impose a pre-defined layout, and you do not need
276    to customize it either as it nicely integrates with your sites`
277    layout.
279  - I think it's rather fast. It uses regexs too, but most of the
280    ewiki_format() uses the simple and quick string functions.
282  - It got rather featureful, the final release seems near :)
286 WikiAlternatives
287 ����������������
288 If you don't like ewiki, then try at least one of these:
290 * PhpWiki has a more complete approach than this WikiWare,
291   get it from http://freshmeat.net/projects/phpwiki,
292   it has support for different database types, features localization
293   and comes with an integrated admin area.
295 * WakkaWiki by Hendrik Mans is also a very powerful PHP implementation,
296   see http://www.wakkawiki.com/
298 * Miki is another nice (small) implementation in PHP from Jukka
299   Zitting.  Get it from http://miki.sourceforge.net/
301 * Finally sfWiki - the sourceforge Wiki (therefore can be found on
302   http://sfwiki.sourceforge.net/). Some of its wiki syntax looks
303   a bit weird (other parts were inspiring), but it features complex
304   user authentication.
306 * coWiki - completely OOP and the source code layout is great; looks
307   very featureful, but is more a CMS than a Wiki (authentication bloat)
308   and has also a little weird markup,
309   but better check it out yourself on http://cowiki.org/
311 * And of course there are Wikis in other scripting languages (and yes,
312   there is still demand for an implementation in assembler or C !!)
313   http://www.freshmeat.net/search/?q=wiki&section=projects or just
314   have a look at http://www.google.com/search?q=wiki
316 * However, the BEST PLACE to look for evil concurrent implementations is
317   http://c2.com/cgi/wiki?WikiEngines
321 Authors
322 �������
323 current maintainer: Mario Salzer <mario*erphesfurt�de> icq95596825 (+Yah,Jab)
324 main contributor: Andy Fundinger <andy*burgiss�com> from http://burgiss.com/
326 For the complete list of authors and contributors please see the CREDITS
327 file.
329 This project is still in an early stage, to improve it further we need
330 to know what doesn't work or what could be enhanced. Every mail is a
331 contribution (yep, that is not measured in lines of source code).
335 Project Pages
336 �������������
337 official freshmeat project page:
338 - http://freshmeat.net/projects/ewiki
340 demo site:
341 - http://erfurtwiki.sourceforge.net/
343 newest versions (unstable development releases):
344 - http://erfurtwiki.sourceforge.net/downloads/
346 mailing list archive
347 - http://www.freelists.org/archives/ewiki/
351 Obtaining Support
352 �����������������
353 Getting support for problems with ewiki is possible, but please read this
354 README first. The author is thankful for BugReports, and of course would
355 like to know were this documentation is not detailed enough and fails to
356 explain things clearly.
357 However, before you send requests to anyone, please visit following site
358 (this is necessary to get FREE support):
360 http://www.catb.org/~esr/faqs/smart-questions.html
362 Then please feel free to contact the author or leave notes on the BugReports
363 or UserSuggestion pages on our project site.
364 Joining our http://erfurtwiki.sourceforge.net/?MailingList would allow you
365 to reach a larger audience for your questions (and you can unsubscribe as
366 soon as your problems are solved).
370 License
371 �������
372 This "program" is "distributed" as "Public Domain". Public Domain
373 is like "FreeWare", but a bit more free ;->  You can think of it
374 as the GPL without being bound to the GPL. <note> I didn't want to
375 include a LICENSE file larger than the program itself. </note>
377 As this is a free (beer) piece of software, you cannot make me
378 responsible for any BUGS or all the REALLY BAD HARD DISK DAMAGES ;-P
379 it may lead to.
381 Additional note: a few plugins contain GPL code, and therefore must be
382 downloaded separately (mime_magic.php, rendering_phpwiki12.php).
386 Known Bugs
387 ����������
388 Currently none. But this note is just here to encourage you to visit
389 http://erfurtwiki.sourceforge.net/?BugReports
395   -------------------------------------------------------------------- 2 --
400 HowTo
401 �����
402 the ewiki script requires:
404 - Webserver (Apache, Nanoweb, ...)
405 - PHP 4.1 or later
406 - a SQL database (works faster if you have one)
407 - your existing web site layout
408 - older PHP's wonderful magic slashes should really be disabled
410 If you don't have the database, there is an add-on for flat-file
411 usage (search this document for "db_flat_files" for notes on how to
412 get this running).
416 Integration with yoursite.php
417 �����������������������������
418 For the next few paragraphs the "yoursite.php" refers to whatever
419 files and/or scripts belong to your already existing website. This
420 hypothetical script should at least output the <html><body> tags
421 around the output from ewiki. The most simple script to accomplish
422 this could look like this (see also example-2.php):
424     <HTML>
425     <BODY>
426     <?php
428        mysql_connect("localhost", "DB-USER-NAME", "PASSWORD");     #[1]
429        mysql_query("use DATABASE-NAME-HERE");
431        define("EWIKI_SCRIPT", "yoursite.php?page=");               #[2]
432        error_reporting(0);                                         #[3]
434        include("ewiki.php");                                       #[4]
436        echo  ewiki_page();                                         #[5]
438     ?>
439     </BODY>
440     </HTML>
442 [1]  The first two commands open a connection to your MySQL database,
443 usually one saves the result of mysql_connect() in a variable named
444 $db or so, but as PHP does not depend on it if there is only one
445 single database connection, it is not used in "ewiki.php" at all.
447 [2]  The define line tells ewiki about the hyperlinks it shall
448 create.
450 [3]  The error_reporting(0) is highly encouraged (but something similar
451 is already built into the ewiki.php script).
453 [4]  The include("ewiki.php") finally loads the ewiki "library" and sets
454 any EWIKI_ constants that have not already been defined here.
456 [5]  The final call to the ewiki_page() function returns the wiki page
457 which was requested by the browser. You must prepend it with
458 "echo" because the ewiki_page() function just returns a <html> enhanced
459 string but does not output that one itself.
463         Creating a "config.php"
464         �����������������������
465         Instead of including the plain "ewiki.php" script as shown in the
466         example above, many people may find it more useful to include()
467         a more customized Wiki yoursite.
469         Customization of ewiki takes place, by pre-defining() some of the
470         EWIKI_ configuration settings and loading extension plugins. To
471         not move that work and code into yoursite it is recommended to
472         create some sort of "config.php" script, which then contained the
473         various define() and include() commands.
474         It is sometimes even senseful to establish the database connection
475         (if you use SQL and not the flat_files backend) inside of such a
476         config script, if there wasn't already established in yoursite.
478         So such a config.php script could contain:
479          - multiple define() commands, setting ewiki behaviour constants
480          - include() comands to load extension plugins
481          - evtl. some include() and define() for the db_flat_files plugin
482            (if you don't have a SQL database)
483          - and last but not least, the include("ewiki.php") script
485         If you then include() such a config.php, you get a fully functional
486         and preconfigured Wiki to include into yoursite. By using this
487         approach, you still could override some of the EWIKI_ settings with
488         additional define() constants right before the include("config.php").
490           <?php
491              include("includes/ewiki/myconfig.php");
492           ?>
493           <HTML>
494           <BODY>
495           <?php
496              echo  ewiki_page();
497           ?>
498           </BODY>
499           </HTML>
501         Note: Please don't get confused by the path names, you of course
502         needed to use a subdirectory specification like "ewiki/" before
503         every filename specified in these include() commands, if this was
504         the dir you put all the ewiki scripts.
508         Generation of a "monsterwiki.php" script
509         ����������������������������������������
510         ewiki over the time grow larger, and nowadays isn't anymore the
511         single script it once was. The distribution ships with over hundreds
512         of extension plugins. But nevertheless it is still possible to build
513         a single script from it all!
515         That being said, the "ewiki.php" script still implements a fully
516         functional Wiki (and just only lacks the advanced features supplied
517         the plugins). - You could still just include() the "ewiki.php"
518         script into yoursite and delete everything else the ewiki tarball
519         contained.
521         However, it is also possible to MERGE all wanted plugins and the
522         core script together to built a customized (feature enhanced) Wiki
523         script from it. All you needed to do was:
525           /unix/$   cat  ewiki.php plugins/*.*  >  monsterwiki.php
526           C:/dos/   type  ewiki.php plugins/*.*  >  monsterwiki.php
528         This way you'd get the "monsterwiki.php" file, which contained the
529         ewiki core script plug all plugins - but of course, you should only
530         copy the ones in, you really need and want (but not "*.*" all as
531         shown in the example above)!
533         The UNIX shell script "tools/mkhuge" will do exactly that for you;
534         it accepts a parameter from 0 to 3, which will merge a custom set
535         of useful plugins into the then generated "monsterwiki.php" script.
537         If you have built a "monsterwiki.php" script, you can include() this
538         instead of the minimal "ewiki.php" into yoursite to integrate a Wiki.
540         Eventually you'd also want to merge some configuration settings into
541         this monsterwiki script, so you wouldn't have to put the define(...)
542         commands into yoursite.php before you include("monsterwiki.php");
543         The define() commands however need to be the very first part merged
544         into that monsterwiki script, so it's best to edit the monsterscript
545         after generation and insert the appropriate settings then at the
546         very beginning.
547         You could also merge a (reduced!) "config.php" into the script,
548         using the above "cat" (or "type" for DOS/Win) method. But beware,
549         that this "config.php" then does not contain any include() command;
550         because else the resulting "monsterwiki.php" script would then try
551         to load the "ewiki.php" core script and plugins which were probably
552         already merged in. Even if you merge such a minimal config script
553         at the start of this monsterwiki script, you still could override
554         some settings (at least establishing the database connection) from
555         within yoursite, if you think it's useful.
557         Additional note: You could still include() plugins, if you included()
558         such a monsterwiki script into yoursite, provided that the plugin
559         you try to include() wasn't already merged into that monsterwiki.php
560         script before (else it would crash the PHP interpreter, because
561         loading it twice is once too much).
563         StaticPages (read about "spages" plugin) can also be included, if
564         you first convert them into ordinary ["page"] plugins using the
565         'mkpageplugin' commandline tool.
569         What to do if images don't work
570         �������������������������������
571         The first example, as well as the "example-2.php" have problems with
572         binary content, because: the <HTML> is output before the 'ewiki.php'
573         library was loaded and got the chance to output pictures.
575         So one should better rewrite the above example yoursite.php script to:
577             <?php
578                mysql_connect(":/var/run/mysqld/mysqld.sock", "USER", "PW");
579                mysql_query("use DBNAME");
581                define("EWIKI_SCRIPT", "yoursite.php?page=);
582                error_reporting(0);
584                include("ewiki.php");
586                $content = ewiki_page();
587             ?>
588             <HTML>
589             <HEAD>
590               <TITLE><?php  echo $ewiki_title;  ?>
591             </HEAD>
592             <BODY>
593             <?php
594                echo $content;
595             ?>
596             </BODY>
597             </HTML>
599         Please again, note the initial <?php part before the very first plain
600         HTML output - yoursite.php must really start with it, or else binary
601         content (uploaded images) won't work!
603         You could, of course write a "binary.php" besides "yoursite.php", to
604         get around this problem; please see fragments/ for an example.
608 Supplying the WikiPageName
609 ��������������������������
610 If you just call ewiki_page() as shown in the first example, it will
611 try to get the name of the requested WikiPage either from the
612 $_SERVER["PATH_INFO"] variable or from one of the GET-variables '?id='
613 or '?name=' or '?page=' or '?file=' (available as $_REQUEST["name"]).
614 If yoursite.php however uses another way or another varname to receive
615 the WikiPageName you can just give it as first parameter:
617   ewiki_page( $id = "WikiPageName" );
619 example-4.php shows how this can be used to list a second WikiPage
620 (the list of newest pages) somewhere else on yoursite.php.
624         mod_rewrite or PATH_INFO
625         ������������������������
626         If you dedicate a complete directory for your wiki, you should keep
627         in mind, that some of the generated URLs contain slashes (for
628         example "edit/WikiPage"), and will look like subdirectories and thus
629         confuse browsers.
631         So you should either set EWIKI_SCRIPT to the absolute directory
632         containing your wiki wrapper script: define(EWIKI_SCRIPT,
633         "http://myserver/wiki/"); or else put a <BASE HREF="..."> into the
634         generated pages. Take this precaution because some of the generated
635         links contain additional slashes (like "edit/ThisPage") and thus may
636         make browsers believe in a changed subdirectory.
638         This applies to mod_rewrite usage and if you call your wiki wrapper
639         with the page name as PATH_INFO (like "/wiki/index.php/WikiPage").
641         Do not forget to enable EWIKI_USE_PATH_INFO, as it is per default
642         disabled for Apache servers! Also check, if EWIKI_URLENCODE and
643         _URLDECODE suit your needs, else you will find it useful to have URL
644         generation encapsulated in the ewiki_script() function.
648         use with the 404 trick
649         ����������������������
650         Once I implemented a way to run a web server below another one
651         (actually Nanoweb below Apache, for more details see
652         http://nanoweb.si.kz/), because the Apache on one of my providers
653         servers was heavily misconfigured - so I handed work over to a
654         secondary WebServer.
656         This trick also works without mod_rewrite support, and is therefore
657         also well suited for cheap WebSpace. Put following into the
658         .htaccess of the dedicated wiki directory:
660           #-- handle "not found" pages by ewiki
661           ErrorDocument 404 /wiki/index.php
662           DirectoryIndex 404 index.php
664         This will allow the "yoursite.php/ewiki.php" script to catch all
665         missed files, which would usually trigger a 404 error. Inside your
666         ewiki wrapper script, you must then however decode the originally
667         requested URL:
669           $url = $_SERVER["REQUEST_URL"];               # Apache often uses this one
670           $url = preg_replace("#^/wiki#", "", $url);    # strip wiki subdir name
671           $_SERVER["PATH_INFO"] = $url;                 # make ewiki see it
673         The second step is very important, it strips the name of the
674         dedicated subdirectory from the URL, which cannot be done inside
675         ewiki.php.
677            The $url from the above example could also be used as $id
678            parameter to ewiki_page().
680         It should be noted, that some Apache implementations are garbaging
681         POST requests in case of a triggered 404 error - but you can simply
682         test this by saving a changed WikiPage.
684         See also the "fragments/404finder.php" example on this.
686         Do not forget to enable EWIKI_USE_PATH_INFO, as it is per default
687         disabled for Apache servers!
694 Security considerations
695 �����������������������
696 ewiki was developed using a PHP5 interpreter, but with limitations of PHP4.3
697 in mind. There are huge differences (a rather instable, bug-prone and still
698 unfinished language) across the 4.x versions of PHP. The 4.0 series is not
699 enough to run ewiki, you'll need at least a PHP 4.1 (4.07) to make it work
700 reliable.
702 One must also know, that there are also differences between the settings of
703 providers. Some for example enforce users to run their scripts in so called
704 "safe mode" (crippled mode) in place of real server security guidelines.
705 Other still use pre-4.3 settings for the PHP interpreter (the Win4 php.ini
706 still is outdated). So take care, and adjust settings using .htaccess`
707 php_option for Apache servers.
711         PHP settings (register_globals)
712         �������������������������������
713         Because ewiki was developed on later PHP versions (at least 4.3), it
714         heavily uses the $_REQUEST array and assumes a deactivated
715         "register_globals" setting in php.ini
716         If this is not the case for your setup / WebServer. or with your
717         provider the ewiki.php script may expose a lot security leaks
718         (because of uninitialized variables).
720         ewiki in general does only use a few global variables, but especially
721         the $ewiki_ring variable (which is used for PROTECTED_MODE) can lead
722         to problems, if you use it without an existing authentication
723         concept.  The $ewiki_plugins is also a very complex task, and I
724         cannot safely state that it won't be able to produce exploits, if
725         the variable is tweaked externally (pushed into by a client).
727         So the best thing you could do is to disable register_globals (this
728         can be done from inside a directories .htaccess file by inserting
729         the line "php_option register_globals off").
731         A fragments/ include will be added to strike against variables which
732         got set from outside (this is rather easy for variables used by
733         ewiki, because their names all start with "$ewiki_").
737         The two modes of operation (_protected_mode and _flat_real_mode)
738         ��������������������������
739         While this wiki was originally developed as a real wiki, many people
740         use it for different things now, like private HomePages, easy CMS on
741         commercial web sites.
743         This fact lead to the support of a restricted operation mode, now
744         known as the _PROTECTED_MODE. It is often used to require people to
745         log in before they can edit pages or upload things. In this README
746         this mode of operation will often be referred to also as the
747         'crippled mode'. It is completely optional, and doesn't have any
748         impact on speed, when left disabled.
750                                   Btw, the standard ewiki operation mode is
751                                           now known as the _FLAT_REAL_MODE.
753         If you'd like to use authentication, you'll probably want to chain
754         some plugins which enable you to use the user database from
755         yoursite.php, so you do not need a separate .htaccess or an
756         additional relational database for passwords. Please see the section
757         on auth plugins.
759         See also the EWIKI_PROTECTED_MODE configuration constant and the
760         separate "plugins/auth/README.auth" file for further and more
761         detailed informations on this feature.
765 simple usage restrictions via wrappers
766 ��������������������������������������
767 The easiest way to cripple a Wiki setup to be browseable-only for the larger
768 public, and to allow only a small subset of users to edit pages is to write
769 two wrapper scripts around the ewiki.php library.
771 One of the wrapper scripts should include and use ewiki as described in the
772 "Integration with yoursite.php" paragraph. You may want to move this wrapper
773 script into a password protected subdirectory (say "/wikiadmin/index.php").
775 Another wrapper script should then be provided for the users that are only
776 allowed to view pages. To disallow editing you'll just have to enrich it
777 with commands like:
779  unset($ewiki_plugins["action"]["edit"]);       # disables editing
780  unset($ewiki_plugins["action"]["info"]);       # no info/ action
781  unset($ewiki_plugins["page"]["SearchPages"]);  # no search function
782  unset($ewiki_plugins["action"]["view"]);       # kill wiki completely
784 This code must occur after you have 'included("ewiki.php");' the library,
785 but before you call the 'ewiki_page();' function, so the unwanted actions
786 and pages really do not get activated.
788 So far the basic approach. If you however have real user authentication
789 code behind the scenes you probably don't want to maintain two different
790 wrapper scripts. You'll then just put the functionality stripping code
791 from above into an if-clause in "yoursite.php" like:
793  if (! $user_is_logged_in) {
794    unset($ewiki_plugins["action"]);            # (do it less destructive ;)
795  }
797 Note: this is again an example, DO NOT copy&paste examples and assume
798 they'll work for you!
802 PhpWiki compatibility
803 ���������������������
804 The MySQL database table is partially compatible to PhpWiki versions 1.2.x,
805 but not with the current PhpWiki 1.3.x versions. There is however now the
806 db_phpwiki13 plugin which allows to access those (rw).
810         Transition from another WikiWare
811         ��������������������������������
812         If you choosed ewiki to replace an already existing wiki script on
813         your site, you should first think about, that the syntax/WikiMarkup
814         isn't equal across all Wikis. There are a few markup extension
815         plugins, that may help you around this, but beware that transition
816         with a larger collection of WikiPages won't be very easy.
818         The best way to import the old WikiPages to ewiki, is to first
819         export it using the tools of the previous WikiWare. You can then
820         just put the produced text/plain PageSource into "init-pages/",
821         because all files found therein (note, that there shouldn't be any
822         file name extension like .txt) are feed directly into the ewiki
823         database, when ewiki is run for the very first time (when the
824         EWIKI_PAGE_INDEX is not found in the db).
826         There is a "plugins/db_phpwiki13.php" which may be useful in first
827         trying ewiki, but it is not recommended to use it for daily work.
828         Speaking of PhpWiki you could also use the "tools/t_convertdb.php"
829         to import (and markup convert) all pages from PhpWiki to the ewiki
830         database format.
837   -------------------------------------------------------------------- 3 --
842 Internals
843 ���������
844 The MySQL database table structure is to a certain degree compatible
845 with that of the well known �PHPWiki� v1.2.x (you only need to change
846 EWIKI_DB_TABLE_NAME to "wiki" to use it). This is the MySQL statement
847 which creates our database table (you can find it at the bottom of the
848 "ewiki.php" script):
849     CREATE TABLE ewiki (
850         pagename VARCHAR(160) NOT NULL,
851         version INTEGER UNSIGNED NOT NULL DEFAULT 0,
852         flags INTEGER UNSIGNED DEFAULT 0,
853         content MEDIUMTEXT,
854         author VARCHAR(100) DEFAULT 'ewiki',
855         created INTEGER UNSIGNED DEFAULT 0,
856         lastmodified INTEGER UNSIGNED DEFAULT 0,
857         refs MEDIUMTEXT,
858         meta MEDIUMTEXT,
859         hits INTEGER UNSIGNED DEFAULT 0,
860         PRIMARY KEY id (pagename, version)
861     )
863 I didn't like the column name {pagename} but as I've seen this was
864 the only difference I renamed it, therefore now the ewiki_database()
865 function translates it from "pagename" to "id" and vice versa most of
866 the time - else this would be really slim and nice code :)
868 The columns {version} holds the different saved page versions. Other
869 Wikis require a secondary "backup" or "history" table for old versions,
870 but as I couldn't imagine what this is for, there is just one table
871 in ewiki; and it seems this is really enough. The first {version} of
872 a wiki page is always numbered 1. An existing page {version} will
873 never get overwritten => very secure MySQL usage.
875 For what's in the {flags}, see the README section about constants. The
876 {content} of course holds the wiki pages source. The {created} and
877 {lastmodified} should be clear too.
879 {refs} contains a "\n" separated list of referenced WikiPages. The
880 code to generate that list is rather unclean, so it often contains
881 GhostPages. However this does not hurt ewiki and the few functions
882 that utilize {refs}, so there is currently no need to slow it down
883 by fixing this.
885 {meta} can hold additional informations, which allows to extend ewiki
886 without requiring to ALTER and convert the ewiki database table. It
887 currently holds some mime headers for binary content and some other
888 useful informations for images and uploaded files.
890 {hits} should have gone into {meta} really. But having it separate
891 allows us to use the very fast mysql UPDATE function.
893 Note, that the ewiki database table can hold other things than wiki
894 pages - binary content (images) for example, depending on the setting
895 of the {flags} field.
897 And last comment about this, the one-table-concept also made it really easy
898 to implement the flat file based "database backend".
902 ewiki_ functions
903 ����������������
904 Some of the core functions of ewiki.php can be used separate from the
905 others and some of them were designed to be replaced by different
906 implementations.
907 Btw, all the functions, constants and variables start with "ewiki_"
908 to make it easier to mix it into other projects (reduces function name
909 conflicts and similar problems, that usually arise if you join two
910 or more scripts into one program).
913    ewiki_page($id)
914    ---------------
915        This is the main function which fetches the selected WikiPage
916        (or the one given with $id) via ewiki_database to transform
917        with ewiki_format().
918        If the requested page does not exist it returns the edit
919        screen.
920        It also includes some virtual pages (InfoAboutThisPage,
921        NewestPages, SearchPage, ReferencesToThisPage, ...).
924    ewiki_page_...()
925    ----------------
926        These functions were separated out from the main ewiki_page()
927        to make it more readable.
928        Most of them contain code to generate the few special/internal
929        WikiPages (Search, Newest, Info, and the Edit <FORM>, ...)
932    ewiki_control_links($id, $data)
933    -------------------------------
934        Prints the line with the EditThisPage and PageInfo, ... links.
937    ewiki_format($wiki_source, $params)
938    ----------------------------------------------------------
939        This returns the formatted (HTML) output for the given WikiSource
940        (with all the WikiMarkup in it).
942        The second param is an array with various config overrides. An entry
943        of "scan_links"=>1 for example tells ewiki_format to lookup the
944        referenced WikiPages in the database (see ewiki_scan_wikiwords) for
945        filling up $ewiki_links. Another $params entry is "html"=>0, which
946        controls interpetation of the <html>...</html> page content blocks.
949    ewiki_render_wiki_links(&$o)
950    ----------------------------
951        Transforms WikiLinks and square brackets in a page into html links.
954    ewiki_scan_wikiwords(&$wiki_source, &$ewiki_links)
955    --------------------------------------------------
956        work with regex on the wiki source text, to find valid WikiWords,
957        the $ewiki_links will be filled with informations if the found page
958        names exist in the DB.
961    ewiki_link_regex_callback()
962    ---------------------------
963        Called from ewiki_format(). To separate the ewiki_format() from
964        the database this function will utilize the global $ewiki_links
965        (generated on demand by ewiki_format) to output either a normal
966        link or a question-mark after the WikiPageName to signal a
967        non-existent page.
970    ewiki_script()
971    --------------
972        Builds the complete URL needed to access the given resource. This
973        function replaces/enhances the static EWIKI_SCRIPT constant and
974        unifies the generated URLs (less bugs). It also helps around
975        various design flaws (like nice looking URL strings), that made
976        some parts of ewiki a bit weird and unreliable in the past. Btw,
977        now the base URL is stored in $ewiki_config["script"].
980    ewiki_script_binary()
981    ---------------------
982        Is just a ewiki_script() wrapper, but can additionally distinguish
983        between binary download and upload URLs, which could be utilized by
984        (database external) plain file storages (see plugins/binary_store).
987    ewiki_binary()
988    --------------
989        Gets called automatically for requests with the ?binary= trailer
990        which is used to reference cached and uploaded images (or not
991        yet cached ones).
994    ewiki_author()
995    --------------
996        returns a string with REMOTE_ADDR and the $ewiki_author or a default
997        string incorporated
1000    ewiki_auth()
1001    ------------
1002        Is a simple interface to a probably large collection of plugins,
1003        which should to actual user and permission management. Support for
1004        this in the core is however still sporadic.
1007    ewiki_auth_user()
1008    -----------------
1009        Queries all registered user databases, and is usually itself called
1010        from within an auth_method/auth_query plugin.
1013    ewiki_t()
1014    ---------
1015      Fetches a text string from the $ewiki_t[] array and additionally adds
1016      some text pieces into it (given as second param). It can retrieve
1017      translations for registered abbreviations, or searches for complete
1018      text fragment replacements. It also understands _{...} to recursively
1019      translate a text snippet inside of larger text blocks.
1020      This is probably a bit slower and less readable than the previous usage
1021      of EWIKI_T_ constants, but it saves some memory and allows to extend
1022      translations or additional text constants (of plugins) a lot more
1023      easier (previously one had to edit inside a function, which is almost
1024      impossible to do from outside / per configuration).
1027    ewiki_make_title()
1028    ------------------
1029      Returns a string enclosing (the generated) page title (as link) into
1030      the html title markup "<h2>". The $class parameter actually tells from
1031      which plugin sort it was called, and this decides if a link will be
1032      generated or the title will be unclickable plain text (the setting in
1033      $ewiki_config["print_title"] is used to determine that). $go_action tells
1034      which action to link the title to.
1037    ewiki_chunked_page(...)
1038    -----------------------
1039      Is a helper function to split large results into multiple click-through
1040      pages, and is used by info/ and some search functions/plugins. It only
1041      produces the click-through links for inclusion on other dynamic pages,
1042      allows overlapping of page chunk ranges.
1045    ewiki_in_array($value, &$array, $dn=0)
1046    --------------------------------------
1047      Case-insensitive variant of PHPs` in_array(), returns the $value if
1048      found. The $array will be all-lowercased afterwards (except when $dn
1049      was set).
1052    ewiki_array($array, $index=false, $am=1)
1053    ----------------------------------------
1054      Returns input-array lowercased (indices), or just the entry for the
1055      $index if searched for. The $am decides if multiple entries should be
1056      merged together (uppercase+lowercase merging produces overlaps).
1059    ewiki_database($FUNCTION, $args=array() )
1060    ------------------------------------------
1061        This function is the "database abstraction" in ewiki. It contains
1062        ''only'' eight SQL statements which must be replaced if you'd like
1063        to use another database server. It is very stupid, and does not know
1064        much about its database (keeping it extensible on the other hand),
1065        therefore one must be careful when passing database entries to it.
1066        The individual "atomic" functions are:
1068        "GET",  $args = array( "id"=>STRING, ["version"=>NUM] )
1069            Fetches the newest wiki page incarnation from the database,
1070            or alternatively the one given by version.
1072        "WRITE",  $args = array( COLUMN-NAME => VALUE, ... )
1073            Saves the contents of the given data array in the database,
1074            does _never_ overwrite an existing entry (you must keep track
1075            of the {version} yourself).
1077        "GETALL",  $args = array( "COLUMN-1", "COLUMN-2", ... )
1078            Fetches an array of all existing pages in the database, but
1079            returns it as ewiki_dbquery_result object, which will throw
1080            the requested columns on ->get(), where the entries 'id',
1081            'version' and 'flags' are always present.
1083        "FIND",  $args = array( "WikiPage1", "WikiPageName2", ... )
1084            Searches the database for the queried page names, returns an
1085            array which associates the boolean value (if pages found) with
1086            their names
1088        "SEARCH",  $args = array( "COLUMN" => "CONTENT" )
1089            Returns only those pages, where the database COLUMN has a content
1090            that matches the requested value; the list of pages is returned
1091            as ewiki_dbquery_result object, where you can access the
1092            individual entries using the ->get() call, which will return the
1093            columns 'id', 'version', 'flags' and the scanned COLUMN of course
1094            unless you ->get("_ALL=1").
1096        The following three actions are not required for correct operation,
1097        but provide additional functionality for some plugins or tools.
1099        "HIT",  $args = array( "id"=>STRING )
1100            Increases the hit counter of the given wiki page by 1,
1101            what is not implemented in db_flat_file.
1103        "OVERWRITE"
1104            Is a wrapper to "WRITE" and does replace existing entries.
1106        "DELETE", $args = array( "id"=>STRING, "version"=>NUM )
1107            Removes the specified page (only the given version) from the
1108            database; implemented in all database plugins but should be used
1109            from within the tools/ only.
1111        Other functions are usually used internally only, as for example the
1112        "ALLFILES" command in dbff or dba/dbm plugins.
1115    ewiki_dbquery_result
1116    --------------------
1117        Has the member variables $keys and $entries, where the latter
1118        contains an array of page names that where triggered by your GETALL
1119        or SEARCH request, and the $keys array contains the column names that
1120        each subsequent "$result->get()" will return.
1122        get()
1123            Returns the database entry array (see GET above), but only the
1124            fields the database query should return (at minimum these are
1125            'id', 'version' and 'flags' and the searched column for SEARCH).
1127        get("_ALL=1")
1128            Instead returns the complete entry.
1130        count()
1131            Returns the number of found database entries.
1133        add($row)
1134            [internal]  This is used by the ewiki_database() core functions
1135            to initialize the $result object with the found entries.
1139 $GLOBALS pollution
1140 ������������������
1141 At least the ewiki_page() function produces variables in the
1142 global namespace. Of course they also were named to not interfere
1143 with anything from yoursite.php:
1145  $ewiki_id      - Contains the current page name, after ewiki_page()
1146                   was called.
1148  $ewiki_action  - Contains the $action/ForTheCurrentPage.
1150  $ewiki_title   - Will be set after the first call to ewiki_page(),
1151                   it is most useful to be printed inside the <TITLE>
1152                   tags inside <HEAD>. So if you want to use it you
1153                   should call ewiki_page() very early, but save its
1154                   output into a variable for later use. This way
1155                   you can make the current wiki pages` title available
1156                   (the _title may be different from the pages _id).
1158  $ewiki_errmsg  - Sometimes used to pass error notices back (ewiki_auth
1159                   does so for example).
1161  $ewiki_links   - Is an array produced by ewiki_format() that associates
1162                   all found WikiPageNames with a value of 0 or 1,
1163                   depending on if the referred page exists in the
1164                   database.
1166  $ewiki_author  - The content of this variable is saved in the author
1167                   field of newly created wiki pages (it will be filled
1168                   with IP:PORT if not set from outside). This is only an
1169                   informational setting, and does not directly correspond
1170                   to the _PROTECTED_MODE.
1171                   You should set it, whenever yoursite.php notes a logged in
1172                   user (so his login gets saved in the wiki pages 'author'
1173                   column). But you should REALLY NOT SPAM IT with your own
1174                   name or ad words.
1176  $ewiki_auth_user  - Is set by ewiki_auth_user() whenever it successfully
1177                   authenticates a user in _PROTECTED_MODE. This variable
1178                   is then used as reliable state setting, which affects
1179                   permission granting.
1181  $ewiki_ring    - Holds the permission level ('ring') of the currently
1182                   authenticated user (or else will be unset). This value
1183                   tells only about the user, many plugin functions have
1184                   built-in requirements which will be compared against
1185                   this value (no value or zero means full permissions).
1186                   While this is the built-in way to grant permissions
1187                   and often also suits the needs to do it, the _auth()
1188                   plugin interface allows to work at a much finer degree
1189                   of access granting.
1190                   values: 0=administrator, 1=moderator, 2=editor, 3=guest
1191                   See also plugins/auth/README.auth for more informations.
1193  $ewiki_plugins - Is an array which connects task names (say "database"
1194                   or "image_resize" for example) to function names.
1195                   You can utilize this if you decide to extend ewiki.
1196                   There is an own chapter on this.
1198  $ewiki_config  - Imports some configuration settings from older constants,
1199                   and introduces newer ones, which can then be overridden at
1200                   runtime. Also holds some work and markup transform data.
1202  $ewiki_t       - Text definitions and translations for all possible
1203                   messages.
1205  Things that disappeared again, and which are now part of the $ewiki_config
1206  array instead include:
1208  $ewiki_data    - May reappear by setting a _config[] variable.
1210  $ewiki_interwiki  - Was errornously part of _plugins[] for some time.
1212  $ewiki_script  - Was a global var for a short period of time, but now is
1213                   a subentry in $ewiki_config.
1218 EWIKI_ constants
1219 ����������������
1220 This chapter explains some of the constants and how you can utilize
1221 them to tweak some of ewiki's behaviour.
1223 The recommended way to change settings is to copy the define() commands
1224 from "ewiki.php" into "yoursite.php" (see our example "config.php"). This
1225 is a good idea, because then your settings won't get lost if you upgrade
1226 to a newer version by overwriting your tweaked "ewiki.php".
1228                    [Note: constants in PHP can be defined() once only, so
1229                    pre-defining them in "yoursite.php" or a "config.php"
1230                    script is nearly like a 'configuration']
1232 To define() some of those constants in 'yoursite.php' is especially a good
1233 thing, because some of them are more used like state variables and it may
1234 be more senseful to set them depending on informations only available in
1235 the scripts of yoursite.php (for example if yourscripts provide a way to
1236 authenticate and login a user you may give him additional rights within
1237 ewiki by pre-defining one of the following constants).
1240  EWIKI_SCRIPT
1241      This is the most important setting. It is used by ewiki.php
1242      to generate links to other WikiPages.
1244      It needs the name of yourscript.php which itself includes
1245      ewiki.php.
1246      The name of the linked WikiPage is just appended to the string
1247      defined here, so you must ensure that it either ends in "/"
1248      or "?id=" or "?name=" or "?page=" so it constructs a valid
1249      URL after concatenation (or %s replaced) with the WikiPageName.
1251      If you utilize mod_rewrite on your server, you may wish to
1252      make it blank when all requests to http://wiki.example.com/
1253      are redirected to the correct script by your WebServer.
1255      If your wrapper script for example is called 'index.php' then you
1256      can just set EWIKI_SCRIPT to "?page=" (which then refers to the
1257      index.php of the current directory).
1258      You should preferrably set it absolute to the servers DocumentRoot,
1259      which gets a requirement if you'd like to give page names and actions
1260      via PATH_INFO "/wiki.php/WikiPage" and not as QUERY_STRING "?id=".
1262      Update: this constant will stay, but the core script now utilizes
1263      the ewiki_script() function (which itself additionally respects
1264      the $ewiki_config["script"] config variable in favour).
1266      ewiki_script() introduces use of the "%s" placeholder inside
1267      EWIKI_SCRIPT, which will be replaced by pagename and action, when
1268      URLs are generated.
1270  EWIKI_SCRIPT_URL
1271      Some parts of ewiki require the absolute URL of the ewiki wrapper
1272      script. So in contrast to the (often) short EWIKI_SCRIPT, this
1273      constant MUST contain the protocol and server name, like:
1274      "http://www.example.com/wiki/index.php?id="
1276      If you do not set this constant, it will be guessed by the
1277      ewiki_script_url() funciton, what often works but may be suboptimal
1278      and could also lead to security problems.
1281  EWIKI_DB_TABLE_NAME
1282      Sets the name of the MySQL database table name to be created
1283      and used to store all WikiPages.
1285  EWIKI_DBQUERY_BUFFER
1286      When set to a value>0 then SQL database buffering will be enabled
1287      for SEARCH and GETALL queries. This is mostly like the old (R1.00)
1288      behaviour (memory exhaustive), but instead is limited to the size
1289      defined by this configuration constant (for example 384K).
1291  EWIKI_DBFILES_DIRECTORY
1292      Defines where db_flat_files puts the database (made up of files).
1293      There is a separate paragraph about this,
1295  EWIKI_DBFILES_ENCODE
1296      If set to 1 will generate urlencoded() filenames even on UNIX
1297      systems, so the dbff database 'files' get exchangeable across
1298      DOS/Win and UNIX filesystems. Not recommended, and will make
1299      ewiki run bogus, if you switch it after there already entries
1300      in the database.
1301      It may however be useful to enable this per default, if you want to
1302      "backup" (this is the wrong way) from a Unix server to a Win box via
1303      an ordinary FTP program (more professional tools could however handle
1304      this more easily).
1306  EWIKI_INIT_PAGES
1307      Names the directory from which the basic pages should be read and
1308      then written into the database, when ewiki is run the very first
1309      time (or the FrontPage - EWIKI_PAGE_INDEX) is still empty.
1310      Btw, you could use the 'ewikictl' utility to export all your Wiki
1311      pages into this directory as auto-reinit-backup.
1314  EWIKI_NAME
1315      Defines the name of your Wiki. (This is not used currently, but
1316      is required, as _PAGE_INDEX is often just set to "FrontPage".)
1318  EWIKI_PAGE_INDEX
1319      This defines the name of the WikiPage which shall be displayed
1320      when no value is received within the URL. Often this is called
1321      the "FrontPage" of the Wiki.
1323      The mysql error message "Table 'ewiki' already exists" will appear
1324      until you create (and fill) the page specified herein.
1326      If you'd like to have a wiki without FrontPage, you can set this
1327      constant to 0 or "" - you must then however ensure, that the ewiki
1328      script is never activated without a page name!
1330  EWIKI_PAGE_NEWEST
1331      This defined the name of the virtual (internally generated) page
1332      containing a list of the lately added WikiPages.
1333  EWIKI_PAGE_SEARCH
1334      Holds the WikiPageName for the search function.
1337  EWIKI_CONTROL_LINE
1338      Pre-define this with 0 before including("ewiki.php") if you
1339      don't want that "<HR><A HREF>EditThisPage</A> ..." to be shown
1340      at the bottom of each page.
1342      You must then generate the EditThisPage link yourself somewhere
1343      else on yoursite.php
1345      It is often easier to edit the ewiki_control_links() function
1346      to match the layout/design of yoursite.php.
1348  EWIKI_AUTO_EDIT
1349      If set to 1 (default) will automatically bring up the edit box
1350      for non-existent pages. Else a page in between will appear ("please
1351      edit me!") like in PhpWiki.
1353  EWIKI_LIST_LIMIT
1354      Number of pages to show up in search queries (and other generated
1355      pages).
1358  EWIKI_PRINT_TITLE
1359      If set to 0 will prevent the page title from being shown on many
1360      pages (generated and database content ones).
1362  EWIKI_SPLIT_TITLE
1363      If changed to 1 will separate WikiPages titles into its different
1364      word parts (only on top of each page).
1367  EWIKI_ALLOW_HTML
1368      Usually you do not want that users are able to add <HTML> tags
1369      inside the WikiPages as this allows for corruption of your page
1370      layout or creation of harmful JavaScript areas.
1372      This is however one of the few constants which could be set by
1373      yoursite.php for logged-in users. If it is set while a user
1374      saves a changed page, then the special EWIKI_DB_F_HTML will
1375      be set for the newly created version, so <HTML> won't be
1376      garbaged by ewiki_format() if another (not logged-in) user
1377      requests the WikiPage next time.
1379      You must start a line with a "|" to actually make the HTML
1380      work within a WikiPage.
1382      If a not logged-in user however re-saves the page this flag
1383      won't be set anymore, so you should be careful about that.
1384      {{edit ewiki.php and define(_DB_F_HTML with 8+16) to change}}
1386  EWIKI_RESCUE_HTML
1387      Was replaced by "plugins/markup_rescuehtml.php", which now allows
1388      for certain 'safe' HTML tags within the wiki source to be used.
1390  EWIKI_HTML_CHARS
1391      If set the rendering function will backconvert html entities which
1392      represent non-latin characters, like &#4234; or &#1324;
1395  EWIKI_HTTP_HEADERS
1396      Allows ewiki to throw HTTP headers, where appropriate. You should keep
1397      it enabled, as it allows for things like RedirectionAfterEdit (when
1398      a page gets saved), and many other useful things.
1399      headers() can often only be sent, if your wiki/yoursite.php is binary
1400      safe, or uses PHPs output buffering (less reliable).
1402  EWIKI_HTTP_HEADERS
1403      Instructs browsers not to cache delivered pages at all. This is often
1404      a good thing, because otherwise unclever caches will prevent the most
1405      recent wikipage version to get seen by users.
1408  EWIKI_CASE_INSENSITIVE
1409      Was only recently implemented, but ewiki is fully configurable now in
1410      regards to WikiLink case. It is enabled per default, and thus allows
1411      referencing any "WikiPage" using strings like "WiKipAgE". This is
1412      believed to be more user-friendly than case-dependency.
1413      Reverting to "binary" page name matching is not fully complete now (our
1414      database scheme was designed for case-insensitivity from the very start
1415      and thus the DB code first needs tweaking before links in ewiki really
1416      get case-dependent.
1419  EWIKI_ESCAPE_AT
1420       Encodes the "@" sign into a html entities, which in the past helped
1421       a little bit against address rippers. But please check out the new
1422       plugins/email_protect.php, which is more effective against email
1423       harvesters.
1426  EWIKI_URLENCODE
1427  EWIKI_URLDECODE
1428       You shouldn't disable both unless you know, you don't need to encode
1429       WikiPageNames (else almost always necessary for sanity and security
1430       reasons).
1433  EWIKI_USE_PATH_INFO
1434       If you have a broken Webserver (like many Apache versions), you may
1435       wish to disable the use of PATH_INFO.
1436       If you ever happen to see "Edit page '/wiki/example-1.php'", you
1437       probably need to disable it.
1440  EWIKI_USE_ACTION_PARAM
1441       Allows the page action command to be given as '&action=...' within
1442       an URL (else only "action/WikiPage" allowed).
1443       If you set this constant to 2, ewiki will also create such URLs
1444       (instead of the usual "edit/PageName" prefix).
1446  EWIKI_ACTION_SEP_CHAR
1447       Defines the character that separates the page name from the action
1448       name in generated URLs. Per default this is the slash, but you
1449       could use something else (like the ":" colon), which however may
1450       have a few drawbacks somewhere else.
1453  EWIKI_DB_F_TEXT
1454      This flag is set for every WikiPage inside the database. Usually
1455      the only flag set on creation of a new page.
1456      Starting from R1.00b previous flags will be copied after applying
1457      EWIKI_DB_F_COPYMASK.
1459  EWIKI_DB_F_BINARY
1460      Used for cached/uploaded images. Prevents a page from getting
1461      shown.
1463  EWIKI_DB_F_DISABLED
1464      If set will prevent the page from being shown. Not useful.
1465      You could more easily unset the TEXT flag to disable page view.
1467  EWIKI_DB_F_HTML
1468      Special flag to allow the current version to include <HTML>
1469      tags regardless of the global EWIKI_ALLOW_HTML setting.
1471  EWIKI_DB_F_READONLY
1472      Prevents a new version to be saved, and thus disallows
1473      editing of the WikiPage.
1475  EWIKI_DB_F_WRITEABLE
1476      Is the reversal of READONLY but only useful if you crippled
1477      ewiki by setting EWIKI_EDIT_AUTHENTICATE, as this flag is only
1478      intended to reallow editing of a page if you disallowed it before
1479      with _EDIT_AUTH (which denies access to _all_ pages).
1481  EWIKI_DB_F_APPENDONLY
1482      Gets implemented by the plugins/append*.php, and allows to lock
1483      a page, in that users can only append to edit (or edit parts of
1484      it). See the plugin description for more details.
1486  EWIKI_DB_F_SYSTEM
1487      Is used to mark internally used data holders (usually serialized()
1488      variables).
1490  EWIKI_DB_F_TYPE
1491      Used internally to separate TEXT, BINARY, DISABLED and SYSTEM entries.
1493  EWIKI_DB_F_COPYMASK
1494      When a new page is created, the flags of the previous version
1495      are ANDed with this value to strip off some unsafe settings.
1496      It could be possible to add the _DB_F_HTML setting to here, but
1497      this would allow HTML to be used by all users if the READONLY
1498      isn't set.
1499      Always keep in mind, that flags could be reimported from previous
1500      versions as well (I'm usure if this could happen).
1503  EWIKI_PROTECTED_MODE
1504      Is an operation mode of ewiki, which activates ewiki_auth() function,
1505      that is utilized from many places to require a permission level (from
1506      authenticated users). Set this constant to 1 to enable this mode.
1507      You'll also need some plugins from plugins/auth/ to make this useful.
1509      If this constant is set to 2, then you don't need a permission plugin,
1510      but can control access to the edit/ function, by setting $ewiki_ring
1511      to 2 (to allow) from within yoursite.php scripts. This setting is also
1512      sometimes referred to as the "ClassicProtectedMode".
1514  EWIKI_FLAT_REAL_MODE
1515      Not a configuration directive, but the opposite to _PROTECTED_MODE ;)
1517  EWIKI_AUTH_DEFAULT_RING
1518      Is the permission level which is to be set, if no user is logged in
1519      currently (defaults to 3 - which means "browsing only").
1521  EWIKI_AUTO_LOGIN
1522      If this is enabled, then ewiki_page() automatically requests for
1523      (re-)presenting the login <form> on startup, if current authentication
1524      isn't sufficient to go any further. Leave this enabled, it helps around
1525      some problems.
1527  EWIKI_EDIT_AUTHENTICATE
1528  EWIKI_ALLOW_OVERWRITE
1529      Outdated (were present in older ewiki versions). See
1530      'plugins/auth/auth_perm_old.php' to get them back.
1533  EWIKI_TMP
1534      Tells ewiki which directory to use for temporary files. The default
1535      value is "/tmp" or whatever the environment variable $TEMP or %TEMP
1536      tells (often "C:\\Windoze\\Temp" or "C:\\Trashcan" on DOS systems).
1539  EWIKI_LOGLEVEL
1540      Log messages are internally separated into four categories:
1541      0=evil errors, 1=warnings, 2=notices, 3=annoying debug stuff.
1542      If you do not want a log at all, just set this constant
1543      to -1 or 357. If you set it to 1 for example, you will see
1544      error and warning messages in EWIKI_LOGFILE.
1547  EWIKI_SCRIPT_BINARY
1548      This requires the REAL absolute address of the ewiki.php
1549      library script (but the database must already be opened).
1550      Needed for the function for cached/uploaded images.
1551      You can set it to almost the same value as EWIKI_SCRIPT if it
1552      is ensured that there is yet no output made, and the headers()
1553      are not already sent.
1555      Usually just "?binary=" works fine (if you use the index.php
1556      way of including ewiki.php).
1558      If you don't want ewiki to use image caching and uploading
1559      functions you would define this to "" or 0, because this disables
1560      the <img href> redirection through ewiki_binary(). You should then
1561      also disable the following two constants:
1563  EWIKI_CACHE_IMAGES
1564      Allow caching of images.
1565      To disable all the image functions (uploading, caching) set this to 0,
1566      as well as EWIKI_SCRIPT_BINARY and:
1568  EWIKI_IMAGE_MAXSIZE
1569      ewiki will scale down images until they get smaller than
1570      the absolute size (bytes) given here. This is true for cached
1571      and uploaded images.
1572      Your database may grow really fast, if you set it too high!
1573      (even if .BMP and .XWD files are discarded normally ;-)
1575  EWIKI_IMAGE_MAXALLOC
1576      Maximum size of image while uploading and resizing it (memory
1577      limits).
1579  EWIKI_IMAGE_RESIZE
1580      Enables the internal resizing functions.
1582  EWIKI_IDF_INTERNAL
1583      Is used to identify uploaded images and data files. Usually you do
1584      not want to change it, especially if there are already uploaded
1585      files; however "chrome://" or "file://localhost/tmp/" could be
1586      funny alternatives to the default "internal://".
1588      Note that the renderer relies only on some unique string to detect
1589      binary references, but the database functions in fact depend upon
1590      "://" to return image sizes on "FIND" calls.
1592  EWIKI_ACCEPT_BINARY
1593      Allows users to upload arbitrary binary files through the image upload
1594      function. You should now rather use the downloads plugin, which adds
1595      a lot of functionality missing better suited for such purposes.
1596      This feature depends on the image upload and cache function.
1599  EWIKI_ADDPARAMDELIM
1600      Automatically defined, holds either "?" or "&" depending on what
1601      is in EWIKI_SCRIPT. You shouldn't change this unless you know what
1602      you are doing.
1605  EWIKI_T_*
1606      These were replaced by the $ewiki_t[] array and ewiki_t() function.
1609  EWIKI_CHARS_U
1610  EWIKI_CHARS_L
1611      Allowed chars in WikiPageNames (uppercase and lowercase chars). Use
1612      this to localize your wiki (standard Wikis only allow A-Z, think of
1613      that when it comes to InterWiki).
1616  EWIKI_UP_*
1617      URL parameters. Changing these may only be necessary, if one is already
1618      evaluated within yoursite.php for other purposes (incompatibilities).
1619      You could also change these just to make some of the generated URLs
1620      look a bit nicer ;)
1623  EWIKI_DEFAULT_LANG
1624      This value is used by a few plugins, that must guess the desired
1625      language of visitors, or the language of a pages content.
1627  EWIKI_CHARSET
1628      ewiki currently only supports the Latin-1 charset, but UTF-8
1629      support is underway. So you should only specify "ISO-8859-1"
1630      or "UTF-8" herein (while most other "ISO-8859-*" are believed
1631      to work too).
1634  UNIX_MILLENNIUM
1635      Ey, don't tell me you're using Windoze ;)
1638  EWIKI_VERSION
1639      Is not used at all. It is just placed on top of every ewiki.php to tell
1640      you, which version you are running currently.
1641      Major releases have a version number like 'R1.00a', while testing and
1642      unstable releases have another number appended 'R1.00a7'.
1645 See the tools/ subdir for a small utility to change the mentioned flags
1646 in the ewiki database table.
1650 $ewiki_config array
1651 �������������������
1652 As it turned out not all configuration settings are as everlasting that
1653 they can be constants (this mainly applies to "look&feel"-settings). So
1654 some of the above mentioned EWIKI_ constants can now be overridden by
1655 settings in the more flexible $ewiki_config[] array.
1657 Usually this array contains index=>value pairs with simple boolean
1658 meanings, but often there are more complex entries and some of its contents
1659 are data/behaviour entries (that were previously/falsely in $ewiki_plugins).
1661 You can override settings by just setting  $ewiki_config["..."]="...";
1662 because the entries in ewiki.php are defaults that do not overwrite any
1663 existing var. So it is really not important if you change things after or
1664 before the 'ewiki.php' script gets included().
1666 ["script"]             Replaced EWIKI_SCRIPT, and is used to define the
1667                        path/URL of the ewiki wrapper script (yoursite.php,
1668                        which at least included the ewiki.php script and
1669                        runs the ewiki_page() function).
1671 ["script_url"]         Should contain an absolute URL to the ewiki wrapper
1672                        script. (replaces EWIKI_SCRIPT_URL)
1674 ["script_binary"]      like EWIKI_SCRIPT_BINARY
1676 ["print_title"]        replaces EWIKI_PRINT_TITLE, but also allows finer
1677                        grained control:
1678                        a 1 says that titles should be added at top of pages
1679                        a 2 states that titles should also link for internal
1680                            and generated pages
1681                        a 3 will make linked titles even for pages, that
1682                            should normally not have them
1684 ["split_title"]        replaces EWIKI_SPLIT_TITLE, defines if pages` titles
1685                        WikiWords should be separated by spaces when displayed
1687 ["wiki_pre_scan_regex"]  Is the regular expression used to separate out links
1688                        from a pages` content to query the database for
1689                        existence of all mentioned WikiPages.
1691 ["wiki_link_regex"]    Is the actual link search regular expression. It is
1692                        responsible for finding WikiWords and things in square
1693                        brackets and ordinary http:// or internal:// WWW-links
1694                        and even email addresses.
1696 ["action_links"][$ACTION1][$ACTION2]  Holds title for $ACTION2 when shown
1697                        on a page activated with $ACTION1 (only "view" and
1698                        "info" get other actions` titles associated currently).
1699                        This is used for the _control_links() for example to
1700                        entitle/show action links.
1702 ["idf"][$TYPE]         Associates arrays with identification (search) strings
1703                        into classes (we have "url" and "img", "obj" for
1704                        example associated with proto:// prefixes or filename
1705                        extension lists).
1707 ["interwiki"][$PREFX]  Connects other Wikis` script URLs to WikiLinkPrefixes.
1710 ["format_block"][$BTYPE]  Defines "block" types, which are scanned for in
1711                        WikiPages (using the given search strings), and then
1712                        handled by specialized ["format_block"] plugins
1713                        (instead of the core ewiki_format() function code).
1715 ["format_params"][]    Contains the default $params, the ewiki_format()
1716                        function will assume, if they weren't overridden
1717                        by the second paramater given to it.
1719 ["wm_..."]             WikiMarkup definitions.
1721 ["htmlentities"]       Used by ewiki_format() to pre-escape <html> in
1722                        wikipages (later some of the escaped html is
1723                        often reactivated).
1727 internal coding explained
1728 �������������������������
1729 This section is to explain some of the coding style of ewiki, and how some
1730 things work. While many parts of ewiki carry good source code comments, it
1731 is always difficult to quickly understand larger scripts like the ewiki one
1732 by just reading it.
1736          how ewiki operates
1737          ������������������
1738          ewiki_page()
1739            - decodes the $id and $action from the GET or POST parameters
1740            - tries to load the page from ewiki_database()
1741            - if this failed then it calls the database init function
1742            - calls some init plugins, calls the _auth() interface
1743            - chains to ["page"] plugins which activate for registered $id's
1744            - alternatively calls a plugin that was registered for $action
1745            - the default however is to render the current page via _page_view()
1746            - adds a page title
1747            - sends the generated output (view page or plugin output) back to
1748              caller (for output into yoursite.php)
1750          ewiki_page_view()
1751            - feeds the current page $data's ["content"] into ewiki_format()
1752            - also decodes paramters (html allowed)
1753            - returns the gererated html back
1755          ewiki_format()
1756            - beatifies the source code (unifies to plain UNIX newlines)
1757            - calls init plugins (wiki source mangling)
1758            - splits source into blocks, calls block plugins
1759            - then goes through each line of the wiki source to generate html
1760            - there is line-start, in-line and complete-markup
1761            - afterwards everything went from source into the $ooo-output var
1762            - first calls the link pre scan regex (which searches for
1763              wikiwords and stores that information into $ewiki_links)
1764            - then calls the wiki-link transformation regex function
1765            - then calls post plugins and returns generated <html>
1767          ewiki_render_wiki_links()
1768            - searches for all (pre-fetched) $ewiki_links in the
1769              ewiki_database ("FIND")
1770            - transforms the wikiwords into html-links
1771            - with the regex and callback func: returns output back to
1772            - ewiki_format()
1774          ewiki_link_regex_callback()
1775            - transform the wiki source snippet returned from the
1776              preg_replace() call into a html link string
1777            - (complicated)
1779          ewiki_$page_plugin_*()
1780            - page plugins return html output, which usually is hardcoded as
1781              strings into them
1782            - provide some interactivity
1784          ewiki_$action_plugins_*()
1785            - activate on pages with special registered $action's
1786            - provide some interactivity (for page editing for example)
1790          used variables
1791          ��������������
1792          Variables in ewiki often have similar names, and are also
1793          regularily passed by reference from one function to another (so it
1794          is in fact the same variable).
1796          $id         - Is often the name of the current page (which is to be shown
1797                        returned as output. The content of this variable is
1798                        also available via the global $ewiki_id [[for plugins
1799                        that do not have the common ($id,$data,$action)
1800                        interface parameters]].
1802          $data       - Contains the entry fetched with the initial
1803                        ewiki_database() call. This is an array of the form:
1804                        array(
1805                           "id" => "CurrentPageName",
1806                           "version" => 1,               # 1 is the lowest possible
1807                           "flags" => 1,
1808                           "created" => 1002056301,
1809                           "lastmodified" => 1002171711,
1810                           "hits" => 235,
1811                           "author" => "localhost (127.0.0.1:4981),
1812                           "meta" => array("Http-Header"=>"X", "setting"=>"val"),
1813                           "content" => "wiki source...",
1814                        )
1816          $action     - The $action with wich the current page was requested
1817                        (most often "view", but everybody also knows "edit").
1819          $uu         - Short for "unused". Is used as temporary variable, especially
1820                        with preg_match() and string functions.
1822          $result     - Used for database queries SEARCH and GETALL.
1824          $row        - Holds temporarily fetched entries from the databases
1825                        (like $data), if page lists are to be generated.
1831   -------------------------------------------------------------------- 4 --
1837 Tweaking
1838 ��������
1839 (this part of the README is also just a collection of random notes)
1843 Just using the wiki source transformation
1844 �����������������������������������������
1845 The ewiki_format function was designed to be used independently from the
1846 ewiki database.
1848   ewiki_format($wiki_source, 0);
1850 It just needs the "wiki_source" as argument and generates a nicely
1851 formatted page from it. All you need to take care about is the
1852 $ewiki_links variable.
1853 Set the $ewiki_links=true ("true" and not "1" or anything else) to
1854 enforce ewiki_format() to treat all references as existing.
1856 To separate the ewiki_format() function out of recent ewiki versions,
1857 you'll also need ewiki_script(), ewiki_link_regex_callback(), ... and
1858 a lot of constants to take with. It is often much easier to just
1859 include("ewiki.php") for using ewiki_format(). You then should however
1860 take care, that the _binary part doesn't get activated by accident. To
1861 prevent this, just put following before the include() statement:
1863   unset($_REQUEST["binary"]);
1864   include("ewiki.php");
1866 If you need it more quickly, or don't want to load the whole ewiki.php
1867 file, then just try the fragments/wiki_format.inc, which is a stripped
1868 down version of an older rendering core function (no WikiLinks, no binary
1869 stuff). Contributed by Frank Luithle.
1873 Customizing ewiki_format()
1874 ��������������������������
1875 There are various markup extension plugins available for ewiki, which
1876 allow you to use BBCode or the syntax of another WikiWare. But if you
1877 have a closer look at $ewiki_config (the defaults are in 'ewiki.php'
1878 around line 200), you'll notice, that you can configure the WikiMarkup
1879 that is to be used.
1880 Various "wm_..." entries map our obscure markup to html <tags> (or at
1881 least fragments of them). So in order to add a feature you could insert
1882 an own rule there. (But keep in mind, that every new WikiMarkup slows
1883 down the transformation function.)
1885 Often you want to append an entry to "wm_style", for example:
1887    $ewiki_config["wm_style"]["==="] = array("<h1>", "</h1>");
1889 Would allow you to write "===SomeText===" in a WikiPage, which then would
1890 display as an far-too-large headline.
1892 You can also add markup with different 'start' and 'end' characters, using
1893 the "wm_start_end" entry in $ewiki_config. For example the following would
1894 render "... ((((some text)))) ..." in a page using the html <kbd> tag:
1896    $ewiki_config["wm_start_end"][] = array(
1897        "((((", "))))",   "<kbd>", "</kbd>",
1898    );
1900 Please see the section on "ewiki_format() internals" on how to write a
1901 ["format_..."] or markup plugin.
1905 Customization using CSS
1906 �����������������������
1907 There are now some interesting ways to style ewiki output, just read on.
1909 Please note, that it in your stylesheets you just write ".wiki" and
1910 REALLY NOT ".ewiki" this time.
1912 Also important is, that we discourage use of the underscore in CSS class
1913 names, because it is simply forbidden there, even if current browsers do
1914 not complain as loudly as the w3c does. (That's just why you'll now see
1915 lots of class names with minus dashes instead of underscores.)
1919 user style classes in pages
1920 ���������������������������
1921 The plugins/markup_css allows you to use CSS classes and style definitions
1922 in WikiPages. With the double at @@ followed by a css classname or command
1923 you start styling a paragraph or parts of the text.
1925   @@classname at the start of a paragraph will
1926   enclose it into a <div class="classname">
1927   completely
1929   But inside of some text, the @@styledef only
1930   affects the part until the next  @@  everything
1931   that comes later won't be enclosed in a <span>
1933 While the css style classes must be defined in your sites` global stylesheet
1934 to take effect, you could also use direct CSS style commands instead. These
1935 also must follow the @@ immediately and may not contain spaces. So something
1936 like @@color:#ff0000; will work, while specifying font names may not always.
1940 rendered page content
1941 ���������������������
1942 If you are not interested in walking around the "ewiki.php" script
1943 when you want to tune how the output looks, you should try to
1944 utilize the (few) CSS classes ewiki defines (it does not include
1945 even one color setting or <font> tag):
1947 <style type="text/css">
1949    p     { font: ... }          // almost every part of the generated
1950                                 // wiki pages is inside a <p>...</p>
1952    em    { ... }                // you could encolour this, if the browsers
1953    strong { ... }               // usual italic is not emphasized enough
1955    .indent                      // to specify a different space-indentation
1957 </style>
1961 pages enclosed in style classes
1962 �������������������������������
1963 The most powerful way to style the content ewiki includes into your site
1964 is to use the generic style class names which enclose every page that comes
1965 from ewiki:
1967    <div class="wiki view ThatPage">
1968       ...
1969    </div>
1971 This <div> is always the outermost tag around the html content that returns
1972 from ewiki_page(). It will always contain the class "wiki", after this
1973 the current page action/ and PageName (the action is usually "view", but
1974 can be also "edit", "info", "links" or something similar).
1976 Keeping this in mind you can easily style all, a few or even just a single
1977 page from ewiki in your stylesheet. (We'll explain it here, because the word
1978 of multiple class names and the cascading way of using CSS is not very
1979 widespread.)
1981 .wiki  {                       // this affects every page ewiki returns
1982    background-color: #ccccff;
1983    font-family: "WikiFont";
1984    ...
1987 .wiki.view  { ... }            // only applies to pages that are "view"ed
1988 .wiki.links  { ... }           // BackLinks
1989 .wiki.edit  { ... }            // when a page gets edited
1991 .wiki.PageIndex  {             // this rule affects only a __single__ page
1992    ...                         // regardless what the "action/" is now;
1993 }                              // useful for "PowerSearch" or "PageIndex"
1995 .wiki.edit.ThisVerySpecialPage {   // this css section applies to just one
1996    ...                             // page again, and this time only when
1997 }                                  // it gets edited
2001 plugin output styling
2002 ���������������������
2003 There often appear special 'pieces' within a rendered page that ewiki
2004 returns, because not everything in the returned html code belongs to the
2005 requested pages` content.
2007 For example the current pages` title needs its own css class, like does
2008 the block of action links ("EditThisPage, PageInfo, ...") below every page,
2009 so it can be distinguished from the pages` text.
2011 Also note again the use of the '.wiki' selector within the following
2012 stylesheet guide and ewiki CSS class overview:
2015 .wiki  h2.page.title  {         // all titles now have it, while many
2016    ...                          // of them include links as well
2019 .wiki.view  .action-links  {    // "EditThisPage, PageInfo, ..." links
2020    ...                          // are inside such a block, like are two
2021 }                               // <hr>'s
2023 .wiki.info  .chunked-result {   // some generated pages (like the history
2024    ...                          // info/ ones) may need to split their
2025 }                               // results; this matches those links
2027   //-- the edit/ pages are separated into
2028   //   following blocks:
2029 .wiki.edit  .edit-box   { ... }
2030 .wiki.edit  .image-upload   { ... }
2031 .wiki.edit  .preview  { ... }
2033   //-- info/ pages contain a history of page versions, each enclosed in
2034   //   a <table class="version-info">, the <tr>s inside can be selected
2035   //   separately:
2036 .wiki.info  table.version-info  { ... }
2037 .wiki.info  .version-info  .action-links  { ... }
2038 .wiki.info  .version-info  .page-author  { ... }
2039 .wiki.info  .page-refs  { ... }
2040 .wiki.info  .page-flags  { ... }
2043 The class naming across most of the extension plugins is not unified, so you
2044 may often need to look it up here - or inside of the plugins source code.
2045 This is at least necessary for calendar and navbar, which follow a very
2046 different naming scheme.
2048 .wiki  .download-entry  { ... }
2049 .wiki  .download-form  { ... }
2050 .wiki  .upload-form  { ... }
2052 .wiki  .image-append  { ... }
2056 Idea Collection
2057 ���������������
2058 Here we'll note some tricks, on how to do this and that. Some of the
2059 following paragraphs also explain workarounds for currently lacking
2060 features.
2064         Multiple Wikis / InterWiki feature abuse
2065         ����������������������������������������
2066         Other WikiWare provides means to have multiple namespaces in a wiki,
2067         what if fact is contrary to the original Wiki idea suggesting a
2068         single flat namespace. ewiki does not support SubWikis or alike, to
2069         get multiple Wikis using one ewiki installation you'll need multiple
2070         layout and config wrappers (each with its own absolute URL and
2071         differen EWIKI_DB_TABLE_NAME or EWIKI_DBFILES_DIRECTORY constants).
2073         This way you'd get two independent Wikis (with two different SQL
2074         database tables, or flat_files directories), and of course links
2075         between those two need a special syntax. And the best approach here
2076         was to use the InterWiki linking feature.
2078         To do so, invent to InterWikiAbbreviations for each of your separate
2079         Wikis and add it to $ewiki_config["interwiki"] as follows:
2081           $ewiki_config["interwiki"]["main"] = "/wiki/main/?id=";
2082           $ewiki_config["interwiki"]["office"] = "/wiki/office/?id=";
2083           $ewiki_config["interwiki"]["tech"] = "http://tech.company.com/?id=";
2084           $ewiki_config["interwiki"]["our-www"] = "http://www.company.com/";
2086         The last one is an example, on how to use the InterWiki feature to
2087         generate references to arbitrary web documents, with a simple syntax
2088         like "[our-www:/customers/pub/rules.html]" - it's somehow standard to
2089         use "company-url:" or "company-www:" as InterWikiAbbreviation for this
2090         purpose.
2098   -------------------------------------------------------------------- 5 --
2103 Explanations
2104 ������������
2105 The next few paragraphs shall enlight more detailed how some things are
2106 handled in ewiki (and why it is that way).
2110 Binary and Text content
2111 �����������������������
2112 Because I'd like to keep it small (see also the "Everything in one
2113 script" paragraph) ewiki also creates just one database table.
2114 Differently from other Wikis this one has the 'flags' setting for
2115 each saved page. And as I successfully used this bad trick in earlier
2116 projects many times to integrate support for hundreds of different
2117 functions (CMS, links, boards/forums, ...) into a single table; I
2118 thought it could be funny to have something like this in ewiki too.
2120 While the image thingi seemed senseful to me, other binary data
2121 cannot be feed into database without helper plugins, because this is
2122 a Wiki script and not an almighty portal software!
2124 Uploading and caching of images requires the EWIKI_SCRIPT_BINARY
2125 constant to be set correctly (no output may be made before "ewiki.php"
2126 is included == "binary safe").
2127 The ewiki_binary() function handles almost all of this, and gets
2128 activated automagically (whenever required) as soon as ewiki.php is
2129 included().
2131 I believe these functions to be rather safe, as there are many sanity checks
2132 throughout the code to separate between _DB_F_BINARY and _DB_F_TEXT content.
2136         Image Uploading
2137         ���������������
2138         The currently most important use for the BINARY flag and image
2139         functions is to upload images with the small form below every page
2140         edit box.
2142         The upload/caching functions can be disabled fully if
2143         EWIKI_SCRIPT_BINARY and EWIKI_CACHE_IMAGES are set empty (or zero).
2145         URLs starting with "internal://" represent the uploaded files. The
2146         string is just a md5() sum generated from the contents of the
2147         uploaded file. This way files won't get saved another time if they
2148         are uploaded twice.  For uploading a JavaScript-capable browser is
2149         recommended. It will work without, but then requires the user to
2150         copy the [internal://...] text (from one window to another).
2152         The color of the temporary upload info screen can only be changed
2153         inside the ewiki_binary() function, currently.
2155         Beware that images usually get downscaled if they are larger than
2156         specified with EWIKI_IMAGE_MAXSIZE (per default 64K).
2160         Images Caching
2161         ��������������
2162         Images are usually redirected through EWIKI_SCRIPT_BINARY, and ewiki
2163         tries to save them inside the database as with uploaded images. So
2164         most of the facts from the previous paragraph apply to this function
2165         too.
2167         You must enable this feature with EWIKI_IMAGE_CACHING, it is shipped
2168         disabled currently.
2169         Adding a ?nocache to the image URL disables this feature for just one
2170         specific image, if _IMAGE_CACHING was otherwise enabled.
2172         Images are downscaled to fit the maximum defined size in
2173         EWIKI_IMAGE_MAXSIZE (bytes) if the PHP libgd extension is available
2174         (else dropped and then always redirecting clients which request
2175         those image).
2179         Image WikiMarkup
2180         ����������������
2181         Usually one writes image references using square brackets around the
2182         url of an image: [http://www.example.com/pics/image.png] or:
2183         [internal://md5md5md5md5md5md5md5md5md5md5md5md5.png]
2185         This will include (inline) the image into the page, when rendered
2186         and viewed.  Using the standard square bracket link entitling syntax
2187         also image references can be named (non-graphics / alternative
2188         text):
2189         [http://www.example.com/pics/image.png | This is an example image]
2190         [http://.../image.pic "or entitle it using double quotes"]
2192         Images can also be "aligned" to either side of the screen, thus the
2193         remaining text will flow around it. To achieve this include spaces
2194         to the left or the right of the image URL:
2196         * picture to the LEFT:   [http://www.example.com/pics/image.png  ]
2197         * picture to the RIGHT:  [  http://www.example.com/pics/image.png]
2198         * CENTRED picture:     [  http://www.example.com/pics/image.png  ]
2200         Note that you must use __two__ spaces, currently!
2202         Image rescaling is possible by appending x=... and y=... as query
2203         string parameters behind the image URL:
2204           [http://www.example.com/pics/image.png?x=160&y=120]
2205         The query string parameters "width" and "height" are also accepted.
2207         If you have an image URL, but you do not want to get that image
2208         inlined into the current page, then just leave out the square
2209         brackets around.
2213         binary_store, direct access
2214         ���������������������������
2215         While storing the binary data together with text pages in the same
2216         database is most often a good thing and suits most sites, there
2217         exists also a workaround/hack to keep this binary data in plain
2218         files. The advantage is a smaller database and possibly a little
2219         speed enhancement (with a large collection of binary things in the
2220         db). However the drawback is, that use of plugins/binary_store is
2221         only transparent to the main ewiki script, but all admin tools/
2222         won't be aware of it.
2224         If you choose to use the binary_store.php plugin, you can also let
2225         ewiki generate URLs directly to the then stored data files if you
2226         just set the EWIKI_DB_STORE_URL constant.
2228         Please see the paragraph on this plugin for more informations on
2229         this.
2233         Arbitrary Binary Content
2234         ������������������������
2235         Set the EWIKI_ACCEPT_BINARY constant, if you'd like to allow any
2236         binary file to be uploaded and saved in the database using the image
2237         upload function.  Uploaded files will show up as ordinary (except
2238         that "internal://" href prefix) links.
2240         Please also note the "plugins/download.php", which does a much
2241         better job than this constant.
2245 $action and $id
2246 ���������������
2247 Inside of ewiki.php you'll see many occurrences of variables named $id and
2248 $action. The $id refers to the current page, which usually is a string like
2249 ThisPage, ThatPage, OrAnotherPage.
2251 Because just having pages wasn't believed to be sufficient enough, there
2252 is also a way to do something with them. That is what the $action tells.
2253 The most often used $action is "view" and is automatically assumed when
2254 no other $action was specified in the current ewiki URL. For non-existent
2255 pages alternatively the "edit" $action may get used instead.
2257 So the $action now delegates control about a requested page to a subfunc
2258 or plugin of ewiki, so the stored data of the page can be used for
2259 something (viewing being again the most common thing to do with it).
2261 "action/ForTheCurrentPage" is how both often looks in conjunction (again:
2262 if there is no "$action/" then "view/" will be assumed). Here the $action
2263 appears in front of the page name separated by a slash. A pagename now can
2264 contain slashes too, because ewiki can figure out, that "view/That/Page"
2265 separates into the $action being "view" and $id is "That/Page" in this
2266 example (the "view" gets mandatory in such cases).
2270         ewiki URLs
2271         ����������
2272         "$action/$id" is most commonly appended as "GET parameter" to an
2273         ewiki URL, after a string like "?id=" or "?page=" - you've already
2274         noticed that!
2276         There are of course other ways to design the URLs ewiki produces
2277         and uses, the PATH_INFO being one of the most favoured alternatives.
2278         (we had a paragraph on this earlier, see on top of this README)
2280         Other Wikis use different URLs too, but you can tweak ewiki easily
2281         to a different behaviour, because you have the chance to pass your
2282         $action and $id to ewiki_page() from different sources. And because
2283         URL generation is encapsulated into the function ewiki_script()
2284         you could easily change just a few lines to make them look like you
2285         desire.
2287         The $action can be passed as "?action=" parameter already (this is
2288         core support), so URLs could for example look like
2289         ".../my/wiki.php?id=ThisPage&action=view" ... or something alike.
2297   -------------------------------------------------------------------- 6 --
2304 Everything in one script
2305 ������������������������
2306 I think its handy to have one script for one task, and as ewiki is not
2307 intended to be used as portal script I think it's senseless to have
2308 always thousands of libs/scripts surrounding it.
2310 However as time went on, it turned out, that it would either slow down
2311 the core 'library' when everything was included into it, or that there
2312 couldn't be much further development at some point.
2314 So packaging useful but non-essential extensions into separate files was
2315 a good decision. Most of the plugin code can however still be inserted
2316 into or appended to the main "ewiki.php" script easily.
2318 As I realized that it really takes some time to edit the source when
2319 including non-standard things I decided to add that simple extension
2320 mechanism. Internally it is represented by the "$ewiki_plugins" array,
2321 which holds an list of alternative functions for various tasks.
2322 This allows to just include("a/plugin.php") for additional functionality
2323 inside ewiki.
2325    Note: if you're going to use almost all plugins, you should think about
2326    merging them altogether into one .php file:
2327    cat plugins/*.php > all-plugins.php
2328    It is much faster to include() just one big .php script, than it is to
2329    let the PHP parser run over twenty small ones (PHP is not interpreted,
2330    but memory-compiled).
2334 database plugins
2335 ����������������
2336 The ewiki.php core script contains a database request function which is
2337 tailored to a MySQL database. However that function is already prepared
2338 to chain to another "database abstraction" function if desired.
2342          MySQL support
2343          �������������
2344          The first implemented, and still most recommended way to use
2345          ewiki is with a MySQL (3.21 or later) database. RDBMS work more
2346          reliably and of course much faster than any other of the ewiki
2347          database backends.
2349          As the core ewiki_database() inside ewiki.php already includes
2350          the MySQL database calls, there is usually nothing to do, but
2351          opening a database connection before ewiki.php is included()
2352          from yoursite.php
2353          Please look at the top of this README for an example.
2355          As PHPs mysql_() functions don't require a db resource link to
2356          be given anymore, the ewiki_database() function does not pass
2357          and thus does not require it too. (If you use more than one MySQL
2358          database, you should take care, that ewiki accesses the one you
2359          accesses least.)
2363          plugins/db_flat_files
2364          ���������������������
2365          If you don't have access to a MySQL database, then just include()
2366          this plugin to save your wiki pages into simple text files (editable,
2367          often called "flat files") inside a dedicated subdirectory. You
2368          must set EWIKI_DBFILES_DIRECTORY in the 'ewiki.php' script to the
2369          correct dirname. Don't forget, that it must be given either relative
2370          to where the ewiki.php script is run from (like "./pages") or
2371          absolute to the servers filesystem root (for example
2372          "/export/htdocs/user528742/www.example.com/ewiki/pages") but NOT
2373          relative to your WebSpaces DocumentRoot!.
2375          Usually "/tmp" will work, but this one is purged on every boot; and
2376          therefore you should create a new sub directory (" mkdir ./pages ")
2377          where all files go into. This newly created subdir must be made
2378          �world-writeable� using the command "chmod 777 ./pages", because the
2379          WebServers user id counts when accessing it.
2381          Usually you can do both from within your ftp client (the commands
2382          are the same if you have a shell account):
2383          ftp> cd .../ewiki
2384          ftp> mkdir pages
2385          ftp> chmod 777 pages
2386          ftp> ls
2387          -rw----r--    1 yourname yourname    57024 01. Jan 00:00 ewiki.php
2388          -rw----r--    1 yourname yourname      512 01. Jan 00:00 index.php
2389          drwx---r-x    2 yourname yourname     4096 01. Jan 00:00 init-pages
2390          drwxrwxrwx    2 yourname yourname     4096 25. Feb 23:59 pages
2391          drwx---r-x    2 yourname yourname     4096 01. Jan 00:00 plugins
2392          -rw----r--    1 yourname yourname    33010 01. Jan 00:00 README
2393          ftp> quit
2395          In graphical FTP clients there is usually a menu entry to set
2396          "access mode" or "access rights" (sometimes "file permissions") of
2397          files and directories equally.
2399          Again: don't forget to set the EWIKI_DBFILES_DIRECTORY constant to
2400          the correct value!
2401          If you create a subdirectory for the page files in the same directory
2402          the main 'ewiki.php' script resides, you usually want to set the
2403          config constant to just "./thesubdirectory" - here you could leave
2404          out the "./" (not required as it only refers to the current path).
2405          Btw, the slash character will work in directory specifications on
2406          windoze systems too (mr. bill once had to introduce a hierarchical
2407          filesystem in DOS 2.0, but choosed the bad backslashes, so no one
2408          should notice where that idea was borought from).
2410          The saved pages are in a format usually referred to as
2411          "message/http" (like www service request) or "message/rfc822"
2412          (internet mail).  They usually look like:
2413            +-----------------------------------------------
2414            | id: WikiPageName\r
2415            | version: 1\r
2416            | flags: 1\r
2417            | author: 127.0.0.1:3054\r
2418            | created: 1046532697\r
2419            | lastmodified: 1046532697\r
2420            | refs: \nErfurtWiki\nNewestPages\n\r
2421            |\r
2422            | !! WikiSourceContent
2423            | <more-text>...
2425          This file format can be exported by the "backup" tool, so you could
2426          easily change from the MySQL database to the flat-files one, if
2427          desired. Each page file exists in different versions, where the
2428          version number is always appended to the saved pages` file name.
2430          EWIKI_DBFILES_NLR converts newlines into the string "\n", but just
2431          for the values of the metadata. So there shouldn't occur much
2432          inconsistency, because the wiki content is saved binary safe in
2433          those "flat files".
2435          Filenames will be heavily converted on Win32 (urlencoded), while on
2436          state of the art UNIX/Linux systems only a few characters are
2437          replaced (slashes into backslashes) to match filesystem requirements.
2439          Problems: dbff WikiPageNames are currently not case-insensitive on
2440          UNIX-filesystems (while the MySQL-table is).
2441          Hits won't get counted; I don't think it is that essential, and it
2442          would take too much effort and time (file accesses) to support this.
2444          Note: You cannot do a "backup" from a Unix server to a Win box by
2445          using a plain FTP program, because many characters are allowed in
2446          Unix filenames but not on Win partitions. If you really want and
2447          need to do so regularily, you could then setup ewiki with
2448          EWIKI_DBFILES_ENCODE enabled from the very beginning. - The better
2449          aproach was to use 'ewikictl' or 't_backup' or 't_transfer' for the
2450          backup task.
2454          plugins/db_fast_files
2455          ���������������������
2456          NOTE: The db_fast_files has been merged into db_flat_files, so both
2457          formats can be read now - at the same time! Updated or new pages will
2458          however always be written in the file format determined by
2459          EWIKI_DB_FAST_FILES (defaults to 0), edit the "db_flat_files.php"
2460          script to change that constant setting, or even add it to your
2461          "config.php" so it was always present.
2463          While "db_flat_files" allows you to edit the WikiPage files (using
2464          any simple text editor), the "db_FAST_files" plugin saves the pages
2465          in a binary&compressed format (utilizing PHP's serialize function).
2467          This generally leads to a speed enhancement. Additionally this also
2468          allowed the PageHit counting to be activated (which is off in plain
2469          flat files).
2471          So you may wish to use this plugin in favour of the older
2472          db_flat_files.  And as now both methods are available at the same
2473          time, you can switch whenever you want.
2475          Most of the setup guide from above is true for this one, too.
2477          An additional configuration constant introduced here is
2478          EWIKI_DBFILES_GZLEVEL, which tells the PHP internal zlib how much
2479          time to spend on compression of the saved pages. Usually the zlib
2480          uses a default of 5, but for speed purposes it is set to 2 here. You
2481          can also set the constant to 0 so the files will get saved
2482          uncompressed (but still in 'binary' format). A value of 9 will give
2483          you the smallest possible files, but this takes a little more CPU
2484          cycles (a bit slower).
2486          This plugin was contributed by Carsten Senf.
2490          plugins/db_any
2491          ��������������
2492          If you use a relational SQL database other than MySQL, then you
2493          may want to give this plugin a try. It itself provides a wrapper
2494          for the PHP database access wrapper libraries ADOdb, PEAR::DB and
2495          dbx().
2496          These wrappers themselves provide unified access to various SQL
2497          databases in contrast to the many highly different db access
2498          functions of PHP. Each of these db access wrappers has advantages
2499          and disadvantages and so none of them is really widespread and many
2500          users of course only jump on one of these trains. Because ewiki now
2501          tries to be 'library' it will use whatever database access wrapper
2502          you already have running on your site or container CMS, and the
2503          highly simplified anydb_*() now tries to make use of it.
2505          The plugin is based upon the current MySQL database backend, and
2506          thus may not be compatible to all proprietary SQL variants other
2507          vendors usually enforce.
2509          Before you can use the db_any plugin you must ensure that you
2510          either already have the PHP dbx extension dll loaded or the PEAR::DB
2511          or ADOdb include files loaded. db_any will like to see an opened
2512          database connection inside of the global '$db' variable. If
2513          yoursite.php hasn't already a connection opened when ewiki.php
2514          gets included, then you should preferably choose to use the
2515          anydb_connect() function to do so (it will choose from PEAR::DB,
2516          ADOdb and PHP dbx interfaces).
2517          The '$db' connection handle can be shared between your site and
2518          ewiki as long as it is a handle for one of the mentioned database
2519          access wrapper libraries.
2523          plugins/db_adodb
2524          ����������������
2525          obsoleted by plugins/db_any
2529          plugins/db_dba
2530          ��������������
2531          including() this plugin enables ewiki to store the WikiPages in the
2532          Berkeley DB file given with the EWIKI_DBA constant.  Your PHP binary
2533          must be compiled with either the "dba" or the "dbm" extension to use
2534          this (and the dba extension requires at least one other database
2535          type to be enabled).
2537          The plugin has a built-in list of preferred dba database types, but
2538          it respects the filename extension of EWIKI_DBA. For example
2539          "wiki.db3" would create a DB3 database file, while "wiki.gdbm"
2540          resulted in a GDBM file, if that php extension was available.
2542          The PHP dba extension can support the db types (if compiled for):
2543          .gdbm
2544          .ndbm
2545          .db2
2546          .db3
2547          .db4
2548          .flatfile
2549          .dbm
2551          If you have the PHP "dbm" extension enabled, wrapper functions will
2552          get enabled, so this works even if the "dba" extension is not there.
2554          The .flatfile is often available even if you haven't compiled your
2555          PHP binary for anything else than "dba". This may also often be
2556          faster than one of the db_flat_files plugins.
2558          If EWIKI_DBFILES_GZLEVEL is set to a value from 1 (fast) till 9
2559          (very good compression, but slow), the saved pages will get
2560          compressed inside the dba database. With 0 this feature gets
2561          disabled.
2565          plugins/db_phpwiki13
2566          --------------------
2567          The original ewiki database table structure was compatible with the
2568          one used in PhpWiki version 1.2.x, however it turned out that the
2569          PhpWiki project has yet not stopped completely and choosed to
2570          implement a more relational table structure with version 1.3
2572          This plugin is only meant for transition __from__ PhpWiki v1.3.x to
2573          ewiki, it should NOT be used to connect ewiki with PhpWiki forever.
2575          Write access is disabled per default, but available. However it is
2576          probably not fully compatible with the database abstraction and usage
2577          of PhpWiki, so it is likely to corrupt your database if you use it
2578          for a longer period of time. This warning is mainly because the
2579          'latestmajor', 'latestminor and 'minor_edit' rows in the PhpWiki
2580          database, because such stuff is not used by ewiki at all. ewiki also
2581          tries to put some of the pages meta data into places where it could
2582          eventually confuse PhpWiki.
2583          Write access is however done nearly as safe as within the ewiki
2584          database access layer (INSERT statement to not overwrite existing
2585          entries).
2587          Again: this plugin is in no way meant to encourage you to keep your
2588          old PhpWiki database!  ;>
2589          Please see also "tools/ewiki_convertdb.php".
2591          If you temporarily enable this plugin within the default/example
2592          "config.php" or the "tools/ewiki_tools_config.php" you can also
2593          utilize the very powerful 'ewikictl' cmdline utility to generate a
2594          copy of your PhpWiki database in one of the backup formats suitable
2595          for later use with ewiki.
2599          plugins/binary_store
2600          ��������������������
2601          Is a hack into the ewiki core, which will store binary/uploaded
2602          files outside of the default ewiki database (as plain files in a
2603          data directory).
2605          Please also see the documentation on top of the plugin file.
2607          Per default ewiki can store "binary" entries beside ordinary text
2608          pages in the database. If you'd like to keep uploaded files/images
2609          out of the db, then this plugin/hack will help. It intercepts ewiki
2610          and saves uploaded data into a plain data file, and instead creates
2611          a "binary symlink" in the database for it (just the binary meta
2612          data will get stored, with a hint on where to later access the plain
2613          data file).
2615          This may sometimes be a speed enhancement and reduces size of the
2616          database, however it has the drawback that only the main ewiki
2617          script can handle this transparently and all admin tools/ fail to
2618          deal with the stored plain data files (no backup support and so on).
2620          By setting the EWIKI_DB_STORE_URL constant correctly (corresponding
2621          to your wiki setup and where you store the data files, compare with
2622          EWIKI_DB_STORE_DIRECTORY) you can make ewiki create URLs directly
2623          to where the stored plain data files reside (they do not contain
2624          ewiki database meta data, and thus could be accessed directly by
2625          http clients/browsers).
2627          Please be sure to configure this plugin by setting _DB_STORE_DIRECTORY
2628          to something more useful than "/tmp", so your uploaded files will
2629          still be there after a reboot.
2633 core enhancements
2634 �����������������
2635 Some really cool features are put into extension plugins, and the most
2636 important, recommended and most often used ones are listed in this section:
2640          plugins/patchsaving
2641          �������������������
2642          If two users concurrently edit a page, then only the first saving
2643          attempt will succeed; which the second user is told by the "This
2644          page version was already saved" failure message.
2646          This plugin works around this by passing the contents of the
2647          concurrent versions through the 'diff' and 'patch' utilities, which
2648          often merges the two different modifications in a new version that
2649          can be saved into the database so there is no need for the failure
2650          message.
2654          plugins/notify
2655          ��������������
2656          This plugin enables users to get notified, whenever someone changes
2657          a watched page. To enable 'watching' one must just place an email
2658          address into the page with following syntax:
2659             [notify:mail@example.com]
2661          This bracket will be invisible, when a page is viewed, so it can be
2662          placed anywhere. The notifications will be sent to this address
2663          as long as the tag is there.
2665          If one wishes to receive notification messages in another language,
2666          this just needs to be added after a comma or semicolon, like:
2667             [notify:pop3@example.net,de]
2668          This is often only necessary for the generic TLDs .com .org .net,
2669          or where language code and TLD differ.
2673          plugins/jump
2674          ������������
2675          Introduces magic markup for page redirection (switching to another
2676          page). Possible notations are:
2678            [jump:OtherPage]
2679            [goto:SwitchToThere]
2681          The EWIKI_JUMP_HTTP setting tells this plugin to send a Location:
2682          and redirect HTTP status when encountering a page [jump:]. Else
2683          this plugin will show up the JumpDestination page without notifying
2684          the browser about it.
2686          It is also possible to perform InterWiki jumps, just be using the
2687          common InterWikiMoniker: syntax.  [jump:WardsWiki:WelcomeVisitors]
2691          plugins/email_protect
2692          ���������������������
2693          This plugin 'ciphers' all valid email addresses inside a WikiPage
2694          for protection against automated spambots. Additionally it
2695          throws fake/trap email addresses to spam spammers databases :>
2697          It ist not integrated into the core script, because some people
2698          may prefer to have email addresses visible (intranet usage).
2699          However it is HIGHLY RECOMMENDED to enable this plugin. Despite
2700          its file size it is rather fast.
2704          plugins/spages (StaticPages)
2705          ����������������������������
2706          The "StaticPages"-plugin allows ewiki to access files in a given
2707          directory. If these files are in text format, ewiki will parse them
2708          as WikiPages. But if you put files with an extension .html, .htm or
2709          .php into one of the specified StaticPages` directories they will
2710          be returned as is from ewiki_page() - the .php files will of course
2711          get executed and their output is returned.
2713          The basename of the files in the directories to be used by spages
2714          will make up the WikiPageName with which the files will be
2715          accessible.
2717          Any given directory (see on top of plugins/spages.php) will be read
2718          recursively. So files in a subdirectory will get available as a
2719          page with a name like "subdir/FileName". If the name of the
2720          subdirectory contains a dot at the end, then the slash will be left
2721          out in favour of a dot: resulted in "subdir.FileName" for example.
2723          PHP scripts in a spages directory however have some restrictions,
2724          like not being able to return headers() or to access most global
2725          variables without use of the $GLOBALS[] syntax. If you rely on
2726          such functionality you should rather write an ordinary page plugin
2727          (which in fact is often much easier).
2728          From the output of .html and .php scripts only the parts between
2729          <body> and </body> will be returned as page content. Any <html>
2730          head area will get stripped, as it would lead to completely invalid
2731          html code if it was returned as is by ewiki_page() into yoursite.
2733          To let this plugin load pages from directories, you should either
2734          edit the array on top of this plugin file, or define() the
2735          EWIKI_SPAGES_DIR (before! including the spages.php script), which
2736          then also would be read in.
2737          Alternatively you could call the ewiki_init_spages() function
2738          yourself to register a directory for processing (after! loading the
2739          spages plugin):
2741            include("plugins/spages.php");
2742            ewiki_init_spages("/var/www/wiki/staticpages/");
2744          You could also use this plugin to inline the ewiki database tools/
2745          as virtual pages.
2747          Btw, it is very easy to make a StaticPage from a ewiki page plugin
2748          and vice versa. Please also note the tools/mkpageplugin which can
2749          convert anything used as StaticPage into a page plugin for easy
2750          including() with other ewiki plugins.
2754          plugins/pluginloader
2755          ��������������������
2756          The pluginloader plugin automatically loads ["action"] and ["page"]
2757          plugins, whenever necessary. This allows to skip dozens of
2758          include() statements within the config.php (which most always just
2759          slow down script startup). It is configured via a static array,
2760          which defines which plugins are allowed to be automatically invoked
2761          on request.
2762          Detailed explanaition is available within this script.
2766          plugins/init
2767          ������������
2768          Handles database initialization using the distributed standard Wiki
2769          files from './init-pages'. Unlike the ewiki-builtin function to
2770          perform that task, this plugin first outputs informational notes
2771          to the user, prior database initialization.
2772          Once you have your SQL or ./files database initialized, you should
2773          disable this plugin (it then isn't be required anymore).
2777          plugins/feature/appendonly
2778          ��������������������������
2779          This plugin (a family of) implements the actual support for the
2780          _DB_F_APPENDONLY page flag. When the flag is set, and this plugin
2781          active, then ordinary users can further only append text to the
2782          page, and won't be able to edit the earlier written parts of it. So
2783          this implements a much softer approach than the _READONLY page
2784          flag.
2786          Also this plugin comes in three flavours, but you can often only
2787          load one of them:
2789          "appendonly" - Really allows just additions to be made to the page,
2790                         each new separated by a horizontal bar.
2792          "appendwrite" - Allows to insert a page separator, which protects
2793                         the upper part from getting edited by ordinary
2794                         users. Everything below a horizontal bar (denoted
2795                         by at least 16 minus signs) or a double horizontal
2796                         bar remains editable by all users.
2797                         This plugin activates only if the _APPENDONLY and
2798                         _WRITEABLE flag is set.
2800          "appendcomments" - stores page additions in an separate database
2801                         entry marked with _DB_F_PART, but allows this part
2802                         to get edited as whole (like "appendwrite" plugin).
2804          The last one is probably not very useful, as it generates some
2805          overhead and in fact is a collection of various workarounds to
2806          accomplish the desired functionality (so it may prove little
2807          lifetime).
2811          plugins/feature/imgresize_gd
2812          ����������������������������
2813          Was extracted from the core during the R1.00f development releases.
2814          Automatically rescales uploaded images, if they are larger than
2815          EWIKI_IMAGE_MAXSIZE.
2816          As it uses the gd2 library, there must be support for this in your
2817          PHP binary. There are a lot of problems on Win32 systems, and also
2818          some Linux binarys (-dev ones) crash constantly if you load this
2819          plugin but don't have the libgd activated or available.
2823          plugins/feature/imgresize_magick
2824          ��������������������������������
2825          Rescales uploaded images via the ImageMagick utility "mogrify",
2826          which is usually only available on UNIX systems. It should however
2827          be fairly simple to make this plugin work with some other image
2828          manipulation tool (at least with Linux).
2832          plugins/feature/spellcheck
2833          ��������������������������
2834          Turns the [preview] button below every page edit box into a
2835          spellcheck function.
2837          You need a working 'aspell' or 'ispell' on your system, or the
2838          PHP internal aspell functions - as it is rather slow it only shows
2839          up the first 20 errors on a page
2843 action/ plugins
2844 ���������������
2845 Action plugins are those, that can be activated ON individual pages. And
2846 usually are shown as links below a page. The ewiki-builtin EditThisPage,
2847 BackLinks and PageInfo are ["action"] plugins for example.
2851          plugins/action/diff
2852          �������������������
2853          Enables to view the differences between two saved page versions
2854          (what changes somebody has done to the page), but it is rather
2855          stupid and guessworking in how it does so.
2859          plugins/action/translation
2860          ��������������������������
2861          This plugin adds a link to the GoogleLanguageTools or AltaVista
2862          BabelFish, which then remotely translated the current page into
2863          the users preferred language. It has support to detect the lang
2864          of the current pages content, to redirect to the right service.
2868          plugins/like_pages
2869          ������������������
2870          LikePages is a search feature of WardsWiki, which scans for
2871          WikiPages whose name is somewhat similar to the one of the current
2872          page (the pagename must be made up of the same WikiWordParts so a
2873          page gets listed).
2877          plugins/action/raw
2878          ������������������
2879          Can be used to download the unrendered Wiki source of a page.
2883 plugins related to hypertext links
2884 ����������������������������������
2885 The linking/ plugin group deals with how links inside the Wiki will look and
2886 work. Some of them are would also fall the "core enhancements" group, while
2887 others are just handy or for link beatification.
2891          plugins/linking/tcn
2892          �������������������
2893          ewiki evaluates the Accept-Language HTTP header modern browser
2894          send with each request. This plugin now automatically brings up
2895          a variant of the current requested page if it finds a match in
2896          the database. To make it work, you need to create pages with
2897          language suffixes in their names like:
2898            ThisPage.es
2899            ThisPage
2900            ThisPage.de
2901          or
2902            OtherPage
2903            OtherPage*nl
2905          Note, that there can always be one page in each name group without
2906          that suffix. This page then will be assumed to be in the default
2907          language set by EWIKI_DEFAULT_LANG.
2909          If multiple page versions are available, then a list will be
2910          printed above the page title to allow users to override the
2911          prefered language guess of this plugin.
2915          plugins/linking/plural
2916          ����������������������
2917          This plugin tries to alias plural and singular page names against
2918          each other. That is, "WikiPage" will be shown, whenever "WikiPages"
2919          was requested (and vice versa).
2923          plugins/linking/autolinking
2924          ���������������������������
2925          The autolinking plugin allows to have automatic links inside the
2926          Wiki for words which exist in the database, but are no real
2927          WikiWords. This is made possible by the companion StaticPage
2928          admin plugin "spages/Admin/PrepareAutolinking", which must be
2929          invoked from time to time to update the db cache entry, which the
2930          autolinking plugin utilizes.
2934          plugins/linking/link_css
2935          ������������������������
2936          Adds CSS classes to the links generated by the Wiki page formatting
2937          kernel, which then allow you to colorize (or to otherwise change
2938          appearance of links) via a style sheet.
2942          plugins/linking/link_icons
2943          ��������������������������
2944          The link_icons plugin prepends icon <img>s before registered link
2945          types, like the link_css plugin adds class="..." attributes to the
2946          html formatted links in every page.
2950          plugins/linking/link_target_blank
2951          ���������������������������������
2952          Adds 'target="blank"' to link tags <a>, which will result in most
2953          browsers opening pages in a new window.
2957          plugins/linking/linkexcerpts
2958          ����������������������������
2959          Adds a short preview text (with <a title="...">) to every link of
2960          a page. This however requires multiple additonal database accesses
2961          (slower) and could enlarge delivered .html page sizes dramatically.
2965          plugins/linking/linkdatabase
2966          ����������������������������
2967          Is a page plugin, which provides a nearly compliant implementation
2968          of the page and link structure export function known from the UseMod
2969          WikiWare and MeatBall:LinkDatabase. This is useful for contributing
2970          to the upcoming InterWikiBatabase and BorgWiki.
2974          plugins/linking/instanturls
2975          ���������������������������
2976          Allows to specify URL abbreviations on one or more summary pages.
2977          This can be done using a table or a definition list to assign
2978          each URL a title, which then can be used on other pages as square
2979          bracket reference.
2981          The 'instanturl_find' plugin in addition allows to use the [find:]
2982          moniker to perform partial searches in the list of URL
2983          abbreviations, but also in the list of interwiki monikers. As
2984          fallback it searches for matching page names or redirects to
2985          Google.
2989          plugins/linking/titlefix
2990          ������������������������
2991          Allows to swap [title|PageName] in square brackers [Page|title],
2992          because that can easily be detected, if the page already exists.
2996          plugins/interwiki/intermap
2997          ��������������������������
2998          This plugin (in fact only a general include) extends the list of
2999          known InterWiki: prefixes with a more complete set merged from
3000          MoinMoin and PhpWiki's interwiki.map.  The links are rather
3001          untested to work at the moment.
3006 appearance/ tweaks
3007 ������������������
3008 There are various plugin hooks within ewiki, which allow to mangle text
3009 strings and data immediately before it would be returned as output.
3013          plugins/appearance/listpages_br
3014          �������������������������������
3015          This plugin will produce <br> separated lists (for SearchPages,
3016          PageIndex, MostVisitedPages, and so on).
3020          plugins/appearance/listpages_ul
3021          �������������������������������
3022          Creates real <ul> lists (WordIndex, CreatedPages, ...) instead of
3023          the &middot; ones, ewiki core would usually return.
3027          plugins/listpages_tbl
3028          ���������������������
3029          The listpages_tbl plugin outputs a table instead of the ordinary
3030          page lists (PageIndex, UpdatedPages, ...). You need to edit its
3031          source to set colours to fit your site layout.
3035          plugins/appearance/fancy_list_dict
3036          ����������������������������������
3037          The WordIndex and PageIndex plugins (unlike the other page list
3038          returning ones like SearchPages and UpdatedPages) can utlize this
3039          plugin to output a pretty dictionary like listing of pages.
3043          plugins/appearance/title_calendar
3044          ���������������������������������
3045          Changes the titles of calendar plugin entries in the database into
3046          a more readable format for page lists (PageIndex, PowerSearch,
3047          UpdatedPages, and so on).
3051 page plugins
3052 ������������
3053 The page plugins provide additional "generated/internal" pages, which have
3054 a standard WikiWordPageName and can thus be referenced easily from within
3055 ordingary WikiPages. But they are of course uneditable (because their
3056 content is 'hardcoded' as PHP code) and most action/ plugins cannot perform
3057 any function on them.
3059 With the rise of the StaticPages plugin, the page plugins are almost
3060 outdated, because all their code could now be extracted into a StaticPage
3061 file, so their code had to be loaded only on request (instead of including()
3062 them regardless if they're needed or not, how it currently is done).
3066          plugins/page/powersearch
3067          ������������������������
3068          This plugins provides a (probably) better search function
3069          with the default page name "PowerSearch". It tries to guess
3070          a value, which tells something about how good a page matches
3071          the searched words and orders the found pages list by this
3072          (possibly not very useful) value. It prints the top 10 results
3073          more verbose.
3077          plugins/page/pageindex
3078          ����������������������
3079          Lists all pages found in the database alphabetically.
3083          plugins/page/wordindex
3084          ����������������������
3085          Lists the word parts of all wiki pages, but requires the
3086          powersearch plugin to be present, because the result is redirected
3087          to there as usually many of the listed words belong to multiple
3088          page names.
3092          plugins/page/imagegallery
3093          �������������������������
3094          Outputs a page containing all cached/uploaded images. The
3095          images are currently not rescaled to fit on the page; this
3096          work is left to the browser.
3097          Needs enhancement.
3101          plugins/page/aboutplugins
3102          �������������������������
3103          Lists all registered plugins (mpi, page, action, task/core). The
3104          name refers to the "about:plugins" page present in recent browsers.
3108          plugins/page/orphanedpages
3109          ��������������������������
3110          Shows up a list of pages, that exist, but are not linked from any
3111          other pages. These is often also called dead pages.
3113          Note that this plugin does not take into account, if any page
3114          can be reached from the frontpage - such a hypertext tree test
3115          would require much more work than realized in here.
3119          plugins/page/wantedpages
3120          ������������������������
3121          Returns a list of pages to which QuestionMarkLinks? currently
3122          exist.
3126          plugins/page/since_updates
3127          ��������������������������
3128          Provides a list of pages with actualization times.
3132          plugins/page/textupload
3133          �����������������������
3134          The virtual TextUpload plugin allows to insert new WikiPages by
3135          uploading text files. It can convert from various formats into Wiki
3136          content, including some proprietary Office file formats, if one of
3137          the possibile filters is avaiable (Unix style file piping).
3138          It also can extract multiple files from a Tarball or ZIP archive
3139          if the according utilities are available (even on DOS/Win systems).
3143          plugins/page/wikidump
3144          ���������������������
3145          Allows to download a gzipped tarball containing all readily
3146          rendered pages as .html files and also images.
3150          plugins/page/interwikimap
3151          �������������������������
3152          Shows up the currently in use InterWikiMap.
3156          plugins/page/hitcounter
3157          �����������������������
3158          Sums up the individual {hits} count of all pages and returns the
3159          overall count.
3163          plugins/page/scandisk
3164          ���������������������
3165          Presents an unserious statistic.
3169          plugins/page/wikinews
3170          ���������������������
3171          Returns the most recently added pages in an overview, that
3172          incorporates a small fragment from the content of those newly added
3173          pages.
3177          plugins/page/wikiuserlogin
3178          ��������������������������
3179          Allows to set a free-form username, which then would be stored into
3180          the database whenever a page was edited.
3184          plugins/page/randompage
3185          �����������������������
3186          Shows up a randomly choosen page from the database.
3190          plugins/page/fortune
3191          ��������������������
3192          Calls the Unix /usr/games/fortune program and prints out returned
3193          content.
3197          plugins/page/ewikilog
3198          ���������������������
3199          Allows to review the content of the 'ewiki.log' file.
3203          plugins/page/phpinfo
3204          ��������������������
3205          Shows the settings of your PHP interpreter.
3209          plugins/page/README
3210          �������������������
3211          Can parse the distributed README file and make a hypertext
3212          presentation from it, for easier reading of the Wiki documentation.
3213          It is printed in <pre> text, but with WikiLinking enabled (which
3214          however is rarely used in the README file). It additionally
3215          presents the README.de and README.auth files.
3219          plugins/page/wikiuserlogin
3220          ��������������������������
3221          Allows to post a username (Note: this one does not do any sort of
3222          real authentication), which is saved in the http client as cookie,
3223          but can afterwards be evaluated as $ewiki_author, so the according
3224          field in the database entries contains a bit more than just
3225          the IP address when a changed page gets saved.
3229 markup plugins
3230 ��������������
3231 The ewiki rendering core is rather fast and consolidated, that was the goal.
3232 However if you ever happen to need more functionality, this can be added
3233 easily by the use of plugins.
3235 Several are already available to emulate the WikiMarkup of other commonly
3236 used WikiWare.
3240          Other WikiWares markup
3241          ����������������������
3242          The WikiWorld still lacks a unified markup (and thus also the
3243          interchangeablity that made html THE standard it today is), and
3244          while ewiki usues nearly MeatBall:WikiMarkupStandard, you may want
3245          to reuse existing pages from another Wiki.
3247          Currently we provide emulation for:
3248          * PhpWiki
3249          * sfWiki
3250          * miki
3251          * bbcode (BulletinBoard, not a Wiki)
3253          But please see the individual files on which (additional) markup
3254          they introduce.
3256          These plugins on occasion only register their markup within
3257          $ewiki_config["wm_*"] settings, but often just perfrom
3258          pre-conversion of foreign markup by utilizing the ["format_src"]
3259          plugin hook (they then pre-convert page content to use ewiki
3260          markup rules before the ewiki_format() kernel performs
3261          transformation).
3265          plugins/markup/css
3266          ������������������
3267          CSS markup allows you to assign visual styles (or semantic CSS
3268          class names) to a block of text (paragraph) or to pieces of text.
3269          @@ is used to start a styled area. The @@ must be immediately
3270          followed by either a CSS class name (without the dot) or with
3271          CSS instructions without any whitespaces.
3272          The following text (after the @@, the class name and a space) will
3273          then be assigned the class until a (possible) next @@ without
3274          attached classname or style definition.
3276          If the @@ occurs at the start of a paragraph it will enclose it
3277          in a <div> with the according style assignment, otherwise (in the
3278          text) a @@ will become a <span>.
3280          See also the explanation and examples in this plugins` comments.
3284          plugins/markup/css_singleat
3285          ���������������������������
3286          This plugin allows you (like the markup_css plugin) to attach CSS
3287          classes to a paragraph of text with just a single @ character:
3289          @JAVADOCLIKE  paragraphs text...
3290          ... ... ... .... ... ... ... ...
3294          plugins/markup/footnotes
3295          ������������������������
3296          Introduces the ability to generate footnotes by placing an
3297          explanation into double curly brackets {{footnote text}}.
3299          You should activate this only if you really need it. Sometimes this
3300          may be useful, but it is rather bad wiki style; because if someone
3301          would like to explain something in more detail he should create a
3302          WikiLink to a new page.  So this should be used for very short
3303          explanations, say incomplete sentences or a book reference and
3304          other things where it really seems bloat to create a new page.
3306          USE THIS RARELY or better not at all!
3307          (this is a feature copied from MS` EvilWiki)
3311          plugins/markup/asciitbl
3312          �����������������������
3313          Allows to use ASCII-Art tables as outputed by lynx and other
3314          console programs inside of WikiPages, which eases life, when
3315          dealing with multiline table cell content.
3319          plugins/markup_complextbl
3320          �������������������������
3321          ewiki allows you to use tables with the || | characters in the wiki
3322          page source. However the html code for the table layout is
3323          hardcoded and cannot be changed on a per-page basis.
3324          This plugin intercepts the wiki source formation process to allow
3325          you to specify html tag attributes inside a table definition like:
3327          |{ border=0 cellspacing=10}  here is  | the table | content |
3328          | 2nd line | 2nd line |{ rowspan=2}  fills two table rows |
3329          |{ colspan=2}  3rd line |
3331          Note, the opening "{" must follow the "|" character immediately.
3333          This code was provided by Hans B Pufal.
3335          It may be a security risk to include it per default, as this allows
3336          to add SomethingScript references as well.
3340          plugins/markup/htmltbl
3341          ����������������������
3342          Provides a block escape to use the standard html <table> code
3343          instead of the limited pipe syntax provided by ewiki. It will parse
3344          for <tr> and <td> tags and strip any not registered attributes to
3345          defend against harm that could be caused by EvilScript additions.
3347          The common html <table> syntax then allows easily to include
3348          multiline table cell content, which is nearly impossible (to edit)
3349          for the "|...|..|" table syntax.
3353          plugins/markup_rescuehtml
3354          �������������������������
3355          Allows to use some 'safe' HTML tags within the WikiPage. This
3356          plugin replaces the previous EWIKI_RESCUE_HTML constant.
3358          Note that those 'safe' HTML tags may also lead to some confusion,
3359          especially if you have a wiki about HTML, because then you cannot
3360          write text about the <STRONG> tag because it will actually always
3361          be interpolated as itself and not as the text string "<STRONG>".
3365          plugins/contrib/rendering_phpwiki12
3366          -----------------------------------
3367          This is the rendering kernel of PhpWiki 1.2 which was made compatible
3368          with the ewiki function set.
3369          It may be useful to reuse old WikiPages, but anyhow most of its
3370          features are supported by the standard ewiki rendering kernel, so
3371          this is just a fun and proof-of-concept plugin.
3372          ..................................................................
3373          : The code of this module is covered by the GPL license, as it   :
3374          : was copied verbatim from the PhpWiki project.                  :
3375          ������������������������������������������������������������������
3379          plugins/rendering_null
3380          ----------------------
3381          If someone would like to use ewiki for a personal homepage, but
3382          prefers HTML over WikiSyntax, then this rendering core replacement
3383          may suit his needs. It allows HTML to be used, but still renders
3384          WikiWords into valid hyperlinks (a few other features from the
3385          original ewiki_format function are also supported, but you can
3386          strip even those).
3390 mpi
3391 ���
3392 The so called "mpi" plugins can be embedded into pages, and produce their
3393 output there. They are loaded on demand (only if it appears that they should
3394 be invoked), but it is possible to include() the individual files regardless
3395 if they would be used or not.
3397 In order to have the mpi plugins available, you must however first load the
3398 mpi dispatcher:
3399    include("plugins/mpi/mpi.php");
3400 Which then takes care of the markup and loading of the requested plugins.
3402 The syntax for calling a mpi plugin is (write this inside of a WikiPage,
3403 when editing it):
3405    <?plugin PluginName  arg="..."  arg2=DDD ?>
3407 Where args are often optional or could even be written without the 'argname='
3408 if only one was required. The name of the mpi plugin is case-insensitive
3409 here.
3411 It is often possible to invoke mpi plugins like ["page"] plugins, if you
3412 create a link inside of the page using the syntax <?plugin-link PluginName ?>
3416          mpi_backlinks
3417          �������������
3418          Prints a list of BackLinks to the current page (the same as when
3419          clicking on the title of a page or on the BackLinks action link).
3420          <?plugin BackLinks ?>
3421          <?plugin BackLinks page=ForThatPage ?>
3425          mpi_multimedia
3426          ��������������
3427          Allows to <embed> multimedia files into a page.
3431          mpi_syndicate
3432          �������������
3433          Embeds remote RSS feeds (abbrv. for "ReallySimpleSyndication" or
3434          "RichSiteSummary") into the current page. It caches the fetched
3435          data for quite some time in a pre-parsed _BINARY database entry.
3439          mpi_insert
3440          ����������
3441          Allows to insert another readily rendered WikiPage into the current
3442          one, usually inside of a <table border="1">.
3446          mpi_localsitemap
3447          ����������������
3448          Is a mix of BackLinks and LinkTree features, and prints the tree of
3449          pages backreferencing to the current one.
3453 visual extensions
3454 �����������������
3455 The hook following plugins utilize is called "append-view". It allows to put
3456 content below a pages contents (after the action links).
3460          plugins/aview/backlinks
3461          �����������������������
3462          Adds the list of BackLinks (references from others to the current
3463          page) to the current page below it (this list is also available,
3464          when a user clicks on the title of a page).
3468          plugins/aview/linktree
3469          ����������������������
3470          Prints the possible (shortest) paths to the FrontPage (determined
3471          by the EWIKI_PAGE_INDEX constant) starting from the current one
3472          below. Calculations and database access required by this plugin
3473          often means a slowdown up to 2 seconds before the page is readily
3474          rendered.
3478          plugins/aview/toc
3479          �����������������
3480          Analyzes a pages headlines and generates a list of contents box
3481          from it, which is inserted as float box on top of it then. Use the
3482          following CSS selector to style it:
3484             .wiki .page-toc {
3485                ...
3486             }
3490          plugins/aview/posts
3491          �������������������
3492          Allows to add separate comment pages, which will then always be
3493          displayed below the current one, but remain editable as standalone
3494          pages. (So the page they are appended to could be marked as
3495          _READONLY).
3499          plugins/aview/threads
3500          ���������������������
3501          Allows to group the pages created using the "posts" plugin into
3502          threads.
3506          plugins/aview/subpages
3507          ����������������������
3508          Adds the list of pages, which appear to be SubPages of the current
3509          one, below it.
3513          plugins/aview/downloads
3514          �����������������������
3515          Shows the uploaded files, which appear to belong to the current
3516          page (individual pages can be treated as upload sections).
3520          plugins/aview/imgappend
3521          �����������������������
3522          Prints an image uploading box below every page, which allows to
3523          append an image without prior clicking EditThisPage (the image
3524          will be automatically appended to the bottom of the page).
3528          plugins/aview/piclogocntrl
3529          ��������������������������
3530          This plugin allows users to select a logo graphic which will be
3531          made available for use in the site template as
3532          $ewiki_config["page_logo"]. Configureable through the internal
3533          image list array.
3537          plugins/aview/aedit_pageimage
3538          �����������������������������
3539          This plugin allows users to select a page image graphic, and is a
3540          mix of the aview/piclogocntrl and page/imagegallery plugins.
3544          plugins/aview/control2
3545          ����������������������
3546          Shows examplarily how to replace the standard "action-links" box,
3547          and adds it on top of the page (including the page title).
3551          plugins/aview/aedit_authorname
3552          ������������������������������
3553          Adds a text <input> field below the edit/ box, which allows to
3554          set the AuthorName which then will get stored, when the page is
3555          saved. This name is then also stored client-side as cookie for
3556          at least 45 minutes.
3558          Before using this plugin, you must consider, that it eventually
3559          allows to override the correct username that ProtectedMode plugins
3560          already provided. And there is no way to prevent users from using
3561          faked names (because this plugin cannot check if a username was
3562          already 'registered' and thus can't initiate a password query).
3566          plugins/aview/aedit_deletebutton.js
3567          �����������������������������������
3568          Adds a JavsScript snippet to allow users to quickly mark a page
3569          for deleterequest, by inserting the link to "DeleteMe" into the
3570          contents, when editing it.
3574 page filters
3575 ������������
3576 A few plugin hooks exist to completely rework generate page output. These
3577 are often used to insert content into the otherwise readily rendered .html
3578 pages (some of the above aview plugins do so, too).
3582          plugins/filter/f_fixhtml
3583          ������������������������
3584          Is a minimal tag balancer (a highly simplified HTML tidy) and can
3585          work around various html code problems that the ewiki_format()
3586          html rendering function has. It is for example specialized to
3587          correct broken html that resulted from WikiMarkupAbuse as for
3588          example nesting text style attributes like this:  __''text__''
3592          plugins/filter/search_highlight
3593          �������������������������������
3594          Evaluates the Referer header sent by many browsers to detect if
3595          a visitor came from a search engine (even the internal PowerSearch
3596          or SearchPages ones) and highlights the searched words in the
3597          current pages body (using CSS).
3601          plugins/filter/fun_chef
3602          �����������������������
3603          Borg, Borg, Borg!
3607          plugins/filter/fun_upsidedown
3608          �����������������������������
3609          Transforms a pages content using letter transformation to make
3610          them readibly from upside down with certain fonts. This however
3611          is a bit tricky for html pages and thus will always wrongly
3612          intermix sentence order.
3616          plugins/filter/fun_wella
3617          ������������������������
3618          Adds a little CSS to make text swirrling on both sides.
3622          plugins/filter/fun_screamomatic
3623          �������������������������������
3624          Detects if someone entered a FULL LINE OF YELLING into a page
3625          when editing it, and then sets a persistent cookie. That cookie
3626          will result in all pages contents to be converted into uppercase
3627          characters.
3631          plugins/filter/f_msiepng
3632          ������������������������
3633          Converts .png <img> references in the WhateverX code required by
3634          all current IE versions to display .png images according to the
3635          specification (which currently only an IE external plugin can handle
3636          correctly).
3640 BloatWiki extensions
3641 ��������������������
3642 ewiki slowly evolves into a well-bloated portal software, and some plugins
3643 already extend it far beyond the scope of an ordinary Wiki.
3647          plugins/module/calendar
3648          �����������������������
3649          The calendar plugin enables you to add an editable calendar to
3650          every WikiPage. It is not a fully integral part of ewiki, and needs
3651          additional calls from yoursite.php to integrate nicely into your
3652          sites layout.
3654          You even don't need to allow a calendar to be added to every page,
3655          you can just include the plugin file and use the _one_ page called
3656          "Calendar" or "YearCalendar", where everybody can make additions.
3658          The coolest about this plugin is, that it nicely integrates into
3659          the common WikiNameSpace.
3661          Just include("plugins/calendar.php"); so it gets available.
3662          In yoursite.php integrate it as follows:
3664          <?php
3665              ...
3667              echo ewiki_page();    // print current pages content, as usual
3669              ...
3671              if (  calendar_exists()  )
3672              {
3673                 ...
3674                 echo calendar();      // print calendar for current page
3675              }
3676              else {
3677                 ...                   // else only a link to the cal. page
3678                 echo "<a href=\"?id=calendar/$ewiki_id\">ShowCalendar</a>";
3679              }
3681          ?>
3683          The calendar() function call emits the html for the calendar of the
3684          currently viewed page (see ewiki_page() call).
3686          The function calendar_exists() only checks for already existing
3687          event entries in the calendar, so the calendar won't show up, if
3688          there isn't yet anything inside (so only the "ShowCalendar" link at
3689          the bottom of the page will link to the still empty calendar). You
3690          can of course leave out this function call or alternatively call
3691          it with calendar_exists($always=true) if you want the calendar to
3692          appear most of the time / or for all pages.
3694          Please note the "fragments/calendar.css" file, which illustrates
3695          how to tweak layout and look of the generated calendars.
3697          This plugin was contributed by Carsten Senf (originally
3698          implemented for good old PhpWiki).
3702          plugins/module/downloads
3703          ������������������������
3704          From the very beginning the ewiki core supported uploading image
3705          files into the database. As time and discussions went on, there
3706          came the idea to allow arbitrary binary files to be inserted too.
3708          The old EWIKI_ALLOW_BINARY way should now be avoided, because the
3709          download plugin adds more functionality and more features, and is
3710          easier and more intuitive to use.
3712          It adds the virtual page FileUpload to insert a file into the
3713          database, and the page FileDownload, which lists all available and
3714          uploaded binary files from the db.
3716          Please note, that due to the use of the database interface, the
3717          file sizes are usually limited to 1-2M (depending on PHP and MySQL
3718          settings), so there may still be some need to reimplement this,
3719          using the antique world-writable incoming/ directory method.
3721          The mime_magic plugin should be used together with this one, and
3722          you should change the icon file names (use the ones from the Apache
3723          distribution for example).
3725          (It may also be a good idea to run a secondary database if you
3726           use it. Have a look at fragments/binary.php, and set up a
3727           secondary ewiki database using it and the db_flat_files plugin.
3728           This is useful, because you then can more easily delete uploaded
3729           files as they don't get saved into a SQL database.)
3731          Different download sections can be defined. The "*" merges all
3732          allowed sections into one list again, and the "**" section even
3733          lists the files attached to pages.
3735          The page attachment link (to append download functionality to each
3736          page) can be revoked by unsetting the $ewiki_plugins["action"]
3737          line in the downloads.php file; so only the default sections are
3738          accepted (and page names rejected).
3740          The plugins/downloads_view.php brings up the list of uploaded
3741          attachments below each page (if existing). It works rather fast
3742          due to an improved database search call, and should therefore be
3743          activated whenever you use the per-page attachments feature.
3745          See also plugins/binary_store.php to keep your SQL database small,
3746          but note its limitations.
3750          plugins/module/tour
3751          �������������������
3752          Provides a shortened view of the current page and all linked ones
3753          (even the backlinked ones). This eases navigation and page content
3754          "scanning" (getting a quick overview).
3759 utility code
3760 ������������
3761 The plugins/lib/ directory contains code and functionality, which often is
3762 required by some of the other plugins (they depend on it then), but which
3763 was too specialized to get part of the ewiki.php core script.
3765 Other extensions in the lib/ subdir didn't match in any of the other plugin
3766 categories.
3770          plugins/lib/cache
3771          �����������������
3772          This plugin stores readily rendered Wiki page content (already in
3773          html format) either into a dedicated directory, or into specially
3774          named _BINARY wiki database entries. This then allows to satisfy
3775          further requests to a page with the saved content.
3777          You should set EWIKI_CACHE_DIR to a useful value (a so called
3778          "chmod 777" directory, so your webserver process can write into it),
3779          or alternatively unset this constant and instead define
3780          EWIKI_CACHE_DB so cache entries get stored into the ewiki database.
3781          The _CACHE_DB constant is just prepended to the name of the current
3782          page to get the name for the database entry for the cache data.
3786          plugins/lib/speed
3787          �����������������
3788          Evaluates the "conditional HTTP request headers" to tell a client
3789          if it could reuse its existing cache entry for a requested page.
3790          This is believed to reduce traffic and also speed up some
3791          applications. However it is still rather untested and could anyhow
3792          lead to some problems (never updating pages for some broken
3793          browsers). The evaluated headers include "If-Unmodified-Since:"
3794          which corresponds to the "Last-Modified:" answer header ewiki
3795          always sends.
3797          However this will only work, if you disable EWIKI_NOCACHE - but
3798          then some browsers will never see updated pages, if they were
3799          misconfigured to not refetch pages, once they got into the internal
3800          browser cache. (But on the other hand, that is users fault ;)
3804          plugins/lib/mime_magic
3805          ����������������������
3806          Implements the mime_magic feature absent from some (older and
3807          misconfigured current) PHP interpreter versions (check your phpinfo
3808          and /etc/mime.types).
3810          This is recommended in conjunction with the downloads plugin to
3811          store correct mime type data, for proper use of icons beside
3812          download links. Also the correct Content-Type header should always
3813          be available, when binary content is delivered.
3814          ..................................................................
3815          : The data of this plugin is covered by the GNU General Public   :
3816          : License.  :
3817          ������������������������������������������������������������������
3821          plugins/lib/navbar
3822          ������������������
3823          Provides a configureable menu for the contents of your Wiki for
3824          inclusion in your site template, which changes depending on which
3825          site area you're currently inside (determined partially by
3826          the linktree plugin).
3830          plugins/lib/protmode
3831          ��������������������
3832          Is an extension package (currently in development) with various
3833          helper functions for ProtectedMode plugins. Especailly useful in
3834          conjunction with the auth-liveuser framework.
3838          plugins/lib/save_storevars
3839          ��������������������������
3840          An example script on how to store additional vars into page entries
3841          of the ewiki database (session like).
3845 admin/ plugins
3846 ��������������
3847 Collects plugins for ewiki / database administration. Often these depend
3848 upon $ewiki_ring==0 (superuser authentication level in EWIKI_PROTECTED_MODE),
3849 otherwise refuse to work for security reasons (some functions are however
3850 available to moderators too, ring level 1).
3852 Some of these plugins may be reimplementation of stuff from the tools/
3853 directory (integrated database tools).
3857          control
3858          �������
3859          Allows changing per-page settings, and adds a easily accessible
3860          "page control" action link below every page.
3862          You can use this to immediately change per-page flags (_READONLY,
3863          _HTML, _DISABLED and so on). Or you can delete a unwanted page as
3864          soon as you discover it.
3865          It also enables you to edit any entries in the {meta} field of
3866          database entries (which sometimes contain HTTP headers, or page
3867          "class" settings).
3868          And the fourth possible action is to easily rename the page (with
3869          letting ewiki adjust all links to it without further intervention).
3873          SearchAndReplace
3874          ����������������
3875          Is a powerful text/content replacement tool. It features regular
3876          expression matching, but can also be used as any other simple string
3877          replace-all tool.
3880          SearchCache
3881          �����������
3882          This tool is intended to create 'shadow pages' (or 'ghost pages')
3883          for ewiki internal/generated pages (the ["page"] plugins), which
3884          usually weren't found by the PageSearch and PowerSearch.  This
3885          admin plugin just innovocates those page plugins and puts their
3886          html output into the database (which then can is found by the
3887          search functions, but is never displayed, because the page plugins
3888          still have precedence over that faked database content).
3892 other plugins
3893 �������������
3894 These plugins actually implement some stuff, one usually should do inside
3895 of the yoursite.php ewiki wrapper script.
3899          plugins/debug/
3900          ��������������
3901          Eventually contains debug plugins.
3905          plugins/auth/
3906          �������������
3907          Contains various (example and ready to use) plugins for the
3908          ewiki_auth() interfaces. This directory contains its own
3909          README.auth, which describes the _PROTECTED_MODE, the _auth API and
3910          available sample plugins in detail.
3914          plugins/auth-liveuser/
3915          ����������������������
3916          Contains the more advanced authentication and permission plugin
3917          bundle for chaining ewiki with the PEAR LiveUser authentication
3918          framework. There is detailed documentation within the README in
3919          this subdirectory.
3923 separate "extra" tarball
3924 ������������������������
3925 There are a few plugins and extensions, which are not packaged into the
3926 distributed ewiki tarball for size reasons. You can obtain it from your
3927 favourite dealer, or from our downloads/ directory as "extra-CVS-*"
3928 tarball.
3929    http://erfurtwiki.sourceforge.net/downloads/
3931 The package currently just contains a minimal spam filter (which after all
3932 isn't very useful for a Wiki site), but in the future will also provide
3933 additional example/ layouts and some image/graphics/icons for layout
3934 beatification purposes.
3943   -------------------------------------------------------------------- 7 --
3949 More separate files
3950 �������������������
3951 Even if one of the project goals was to have everything in one script,
3952 there are now some support scripts around it, but those are normally
3953 only required for setup (init-pages for example). With some others you
3954 need to take a lot of care before installing on a public WebServer
3955 (the tools/ for example).
3959 Pages in init-pages/
3960 ��������������������
3961 This directory just contains text-files with the wiki_source of the
3962 initial pages, which are inserted if you start ewiki.php for the
3963 first time.
3964 You can create these files with the tools/ewiki_backup.php script
3965 or the 'ewikictl' commandline utility.
3969 Additional tools/
3970 �����������������
3971 This directory holds some (external) add-ons, which are intended to
3972 supply "admin functions" for the ewiki database.
3973 It is strongly discouraged to integrate this with ewiki, as it could
3974 be dangerous to have them always around and usually such stuff just
3975 complicates things (wiki's should be easy to use).
3977 Per default you will be presented a HTTP Basic AUTH login dialog box
3978 by your browser if you try to use one of the www tools. This is made
3979 to prevent other people from doing any harm to the setup.
3980 In the "tools/t_config.php" script you'll see a link (include) to
3981 "fragments/funcs/auth.php", which is responsible for this integrated
3982 security feature. Just insert a username and a password here to start
3983 using one of the tools/.
3984 Please keep in mind, that the $passwords array of that ".../auth.php"
3985 script has nothing to do with the _auth API or EWIKI_PROTECTED_MODE.
3987 Because the www tools (all stuff named "t_*.php") use the "ewiki.php"
3988 script and the sample "config.php", you eventually need to configure
3989 these tools separately (they don't need any ewiki plugins, but the
3990 database ones, if necessary). So if there are problems (for example
3991 if your ewiki setup is configured with ewiki_auth, which then could
3992 overlap with the ".../auth.php" script), you may need to edit the www
3993 tools own "t_config.php" accordingly. (Note: This is not required for
3994 the default setup.)
3996 If you'd like to integrate the tools/ as virtual pages into ewiki, then
3997 the StaticPages plugin will help. You then needed to remove the line
3998 that tries to re-include() your config.php and ewiki.php from the tools/
3999 "t_config.php" script (else you'll break ewiki).
4000 To load your tools/ as static pages into the wiki, you then just needed
4001 a call to ewiki_init_spages() with the "./tools/" directory as parameter.
4005          tools/t_flags
4006          �������������
4007          WikiPages usually have the page flag TEXT assigned. Other possible
4008          flags are DISABLED, SYSTEM, BINARY or HTML, READONLY, WRITEABLE.
4009          Usually page flags are copied from one page version to the next.
4013          tools/t_backup
4014          ��������������
4015          Use this to make backup files from the WikiPages. This www script
4016          is a wrapper around the ewikictl commandline utility and library,
4017          and therefore supports almost the same options.
4021          tools/t_restore
4022          ���������������
4023          Allows to reinsert the files generated with the backup utility into
4024          the database. It is also a www wrapper around ewikictl and thus
4025          also supports the "plain", "flat" and "fast" file formats.
4029          tools/t_remove
4030          ��������������
4031          Use this to delete a page from the database (including all saved
4032          versions).
4033          You should always prefer to set a page DISABLED with the ewiki_flags
4034          tool to hide unwanted content. -- make love() not unlink()
4038          tools/t_holes
4039          �������������
4040          If pages are edited often / regularly you will soon get hundreds of
4041          saved page versions. As this slows down (particularly the
4042          db_flat_file ones) and enlarges the database content size, you may
4043          want to strip old versions.
4045          This tool suggests you to remove a few page versions. You should
4046          however NOT DELETE the page VERSION ONE and the very last (newest)
4047          page version (of course).
4048          The page version 1 often contains control data, not found in newer
4049          versions, when db_flat_files or db_dba is used, so please keep
4050          aware of this.
4052          There were some changes necessary in db_flat_files to support
4053          those "version holes", but it currently seems to work stable.
4056          tools/t_textinsert
4057          ������������������
4058          Can insert plain text files into the database. This is much the
4059          same, what usually happens to the files inside init-pages/
4063          tools/t_transfer
4064          ����������������
4065          Allows to download all pages in one big "binary" file, and to
4066          reinsert it on the same way. This allows for quick moving of
4067          the whole database content.
4071          tools/t_revert
4072          ��������������
4073          Can undo mass changes caused by a script attack (specifically
4074          designed to spam or corrupt a Wiki) or someone who put enourmous
4075          energy into garbaging multiple pages. The {auther} field always
4076          contains at least an IP address to allow easy tracking of such
4077          activity, and this plugin just enables you to remove page versions
4078          whose {author} field matches a certain string (the attackers IP
4079          address).
4083          tools/ewikictl
4084          ��������������
4085          ewikictl is a commandline based utility - as opposed to the
4086          www/http based scripts mentioned above.
4087          UNIX people will find it very useful and handy, while it is
4088          believed to work on Win32 systems too.
4090          It integrates a lot functionality of the web based tools/, some
4091          of them less flexible and others more powerful than in the
4092          other tools. It, for example, allows to generate database backups
4093          automatically and is often easier to use. On the other hand it
4094          will be of little use if you don't have a shell account on the
4095          WebServer running your wiki (because most times one cannot make
4096          remote mysql server connections).
4098          The most important feature is to make backups using the
4099          --backup switch: