
ewiki code fragments/ and tools/
================================

Unlike the plugins/ the code snippets and asorted data files in fragments/
can be included() directly into yoursite.php and are sometimes also
unspecific to ewiki. And the init-pages/ for example are required only once
and can be removed after initialization.
The tools/ is a separate bundle of administration tools for the ewiki
database. They are separate from the main Wiki (even comes with a different
'config.php') to enhance safety and reliability.


        1 fragments/
      1.1 strip_wonderful_slashes.php
      1.2 strike_register_globals
      1.3 404finder.php
      1.4 htaccess
      1.5 binary.php
      1.6 force_lang_de.php
      1.7 fragments/funcs/*
      1.8 fragments/css/*
      1.9 fragments/blocks/*
      1.a fragments/patches/*
      1.b fragments/php-patches/*
        2 Additional tools/
      2.1 tools/t_flags
      2.2 tools/t_backup
      2.3 tools/t_restore
      2.4 tools/t_remove
      2.5 tools/t_holes
      2.6 tools/t_textinsert
      2.7 tools/t_transfer
      2.8 tools/t_revert
        3 commandline tools/
      3.1 tools/ewikictl
      3.2 tools/wiki2html
      3.3 tools/mkhuge
      3.4 tools/mkpluginmap
      3.5 tools/mkpageplugin
      3.6 tools/mkxpi
      3.7 tools/php5fix
        4 examples/
      4.1 examples/homepage.php
        5 Pages in init-pages/




  -------------------------------------------------------------------- 7 --




fragments/
ŻŻŻŻŻŻŻŻŻŻ
This directory holds some files to integrate ewiki.php within some
other web projects (for example PhpNuke) or some helper and extension
code, but even data files, code patches.

Most stuff is grouped into subdirs:

  blocks/       plugin extractions to get included() somewhere into yoursite
                (onto left or right side, like in one of those portal scripts)
  head/         also output html snippets, for inclusion into the html <head>
                area of pages
  css/          for sample .css files and per-page .css definitions (for use
                with 'fragments/css.php')
  funcs/        code snippets of varying usefulness
  parent-cms/   samples on how to integrate ewiki into CMS or portal scripts
  patches/      code/feature tweaks
  php-patches/  PHP interpreter bugfixes
  ./            assorted stuff, described below:



         strip_wonderful_slashes.php
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         If you have a PHP 4.1 or a provider using the annoying factory-default
         settings of such a version, you may find this tiny script helpful.
         It removes the just-for-security-reasons-added-backslashes from the
         $_REQUEST variables. I wasn't very interested in adding hundreds of
         stripslashes() calls inside ewiki.php, so this is the workaround for
         __your__ providers broken php.ini

         It does not hurt a well configured PHP interpreter setup.



         strike_register_globals
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Tries to secure the $GLOBALS environment for PHP setups with the
         register_globals still turned on (which is a bad thing!).



         404finder.php
         ŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Simple example on how to use "ErrorDocumet 404" rediriction to
         activate the ewiki page search function automatically, which is the
         poor mans mod_rewrite.



         htaccess
         ŻŻŻŻŻŻŻŻ
         To make a Wiki installation look more profession you should try to
         use your Webservers mod_rewrite module to get nicer looking URLs.
         This file is an example to be installed as ".htaccess" (Web server
         per-directory configuration file), which allows to call your ewiki
         wrapper using URLs like:

            http://www.example.de/wiki/SomePage
            http://www.example.de/wiki/edit/OneOfThePages

         (For this example, you needed to set EWIKI_SCRIPT to "/wiki/").
         This example '.htaccess' script shows how to instruct mod_rewrite
         to catch above URLs and to transform them into ".../index.php?id=Page"
         again before calling the script.

         +++

         Shows how to use mod_rewrite with ewiki.

         * old style:  http://www.example.com/wiki.php?page=WikiPage
         * PATH_INFO:  http://www.example.com/WikiPage

         Remember to enable EWIKI_USE_PATH_INFO inside ewiki.php - this was
         disabled once, because of the many broken Apache implementations (they
         seem to support that broken CGI/1.1 specification, which was for good
         reasons and luckily never blessed to become an official RFC).



         binary.php
         ŻŻŻŻŻŻŻŻŻŻ
         If yoursite.php (ewiki wrapper) is not designed carefully enough
         (=not binary safe, because <html> or text is written before the
         ewiki.php core script got included) or EWIKI_SCRIPT_BINARY cannot be
         set correctly, you may want to use this wrapper script to allow for
         uploading and retrieval of binary content (images) via ewiki.

         Copy it to where the main ewiki.php script is, and set the
         EWIKI_SCRIPT_BINARY constant to the correct absolute position
         (possibly including http://server.name/) of "binary.php".  (this
         constant must be set on top of ewiki.php)

         You must set the database access params in here, too.

         It may also be useful if you'd like to divide the database into its
         two parts again - text content and binary content. You could even
         let it save binary content in a flat file database, while WikiPages
         remain in a RDBMS.



         force_lang_de.php
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Sample pre-config script for "de_DE" lang to preset the language
         appearance of ewiki.  If you just are too lazy to set up your
         browser correctly, then this line usually fixes your language
         setting problem:

            $_SERVER["HTTP_ACCEPT_LANGUAGE"] = "de";

         (must be written before ewiki.php gets included)



         fragments/funcs/*
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         The funcs/ subdirectory contains code snippets, that provide
         additional interface functions.



                fragments/funcs/auth.php
                ------------------------
                Include this script wherever you need authentication. It
                uses the HTTP Basic Authentication scheme, but the passwords
                are inside the script in the $passwords array (so no need
                for .htpasswd setup).

                Note that this script needs to be called before any body
                output is made (else it would be too late for http header()
                output).



                fragments/funcs/wiki_format.inc
                -------------------------------
                This php include() file contains just the reduced
                wiki_format() function, the code to generate internal
                WikiLinks and the binary data stuff has been removed.  It is
                best suited to allow rendering of WikiSource with other php
                projects.

                The script was contributed by Frank Luithle.



         fragments/css/*
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Please understand the *.css as examples that illustrate which style
         classes are defined inside ewiki.php and its companion plugins.

         Remember, you could insert those files with PHPs` include(), too -
         if desired (and if a <style> area is currently to be written to
         stdout).

         The 'fragments/css.php' script can be included into yoursites`
         page html <head> part and inserts all *.css files from this
         directory which match the current page or action name. This allows
         for restyling certain pages and helps in keeping a sites main
         stylesheet small.



         fragments/blocks/*
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Contains small include() scripts to be loaded into "yoursite.php"
         as "sidebars" and the like for beatification purposes.
         Oftens these are reduced but useful ["page"] or ["action"] plugins,
         performing common tasks, like printing the list of newest pages or
         some sort of menu, or even random page links.



         fragments/patches/*
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         In the patches/ directory some code tweaking tips are collected
         that are either not worth a new plugin or to uncommon and unsafe
         and unsupported to get into fragments/ or plugins/. Please see the
         README and the files therein for more informations.



         fragments/php-patches/*
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         If bugs in the PHP language interpreter prevent running of ewiki
         under certain versions, a patchfix will appear in the php-patches/
         directory.



Additional tools/
ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
This directory holds some (external) add-ons, which are intended to
supply "admin functions" for the ewiki database.
It is strongly discouraged to integrate this with ewiki, as it could
be dangerous to have them always around and usually such stuff just
complicates things (wiki's should be easy to use).

Per default you will be presented a HTTP Basic AUTH login dialog box
by your browser if you try to use one of the www tools. This is made
to prevent other people from doing any harm to the setup.
In the "tools/t_config.php" script you'll see a link (include) to
"fragments/funcs/auth.php", which is responsible for this integrated
security feature. Just insert a username and a password here to start
using one of the tools/.
Please keep in mind, that the $passwords array of that ".../auth.php"
script has nothing to do with the _auth API or EWIKI_PROTECTED_MODE.

Because the www tools (all stuff named "t_*.php") use the "ewiki.php"
script and the sample "config.php", you eventually need to configure
these tools separately (they don't need any ewiki plugins, but the
database ones, if necessary). So if there are problems (for example
if your ewiki setup is configured with ewiki_auth, which then could
overlap with the ".../auth.php" script), you may need to edit the www
tools own "t_config.php" accordingly. (Note: This is not required for
the default setup.)

If you'd like to integrate the tools/ as virtual pages into ewiki, then
the StaticPages plugin will help. You then needed to remove the line
that tries to re-include() your config.php and ewiki.php from the tools/
"t_config.php" script (else you'll break ewiki).
To load your tools/ as static pages into the wiki, you then just needed
a call to ewiki_init_spages() with the "./tools/" directory as parameter.



         tools/t_flags
         ŻŻŻŻŻŻŻŻŻŻŻŻŻ
         WikiPages usually have the page flag TEXT assigned. Other possible
         flags are DISABLED, SYSTEM, BINARY or HTML, READONLY, WRITEABLE.
         Usually page flags are copied from one page version to the next.

         

         tools/t_backup
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Use this to make backup files from the WikiPages. This www script
         is a wrapper around the ewikictl commandline utility and library,
         and therefore supports almost the same options.



         tools/t_restore
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Allows to reinsert the files generated with the backup utility into
         the database. It is also a www wrapper around ewikictl and thus
         also supports the "plain", "flat" and "fast" file formats.



         tools/t_remove
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Use this to delete a page from the database (including all saved
         versions).
         You should always prefer to set a page DISABLED with the ewiki_flags
         tool to hide unwanted content. -- make love() not unlink()



         tools/t_holes
         ŻŻŻŻŻŻŻŻŻŻŻŻŻ
         If pages are edited often / regularly you will soon get hundreds of
         saved page versions. As this slows down (particularly the
         db_flat_file ones) and enlarges the database content size, you may
         want to strip old versions.

         This tool suggests you to remove a few page versions. You should
         however NOT DELETE the page VERSION ONE and the very last (newest)
         page version (of course).
         The page version 1 often contains control data, not found in newer
         versions, when db_flat_files or db_dba is used, so please keep
         aware of this.

         There were some changes necessary in db_flat_files to support
         those "version holes", but it currently seems to work stable.


         tools/t_textinsert
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Can insert plain text files into the database. This is much the
         same, what usually happens to the files inside init-pages/



         tools/t_transfer
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Allows to download all pages in one big "binary" file, and to
         reinsert it on the same way. This allows for quick moving of
         the whole database content.



         tools/t_revert
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Can undo mass changes caused by a script attack (specifically
         designed to spam or corrupt a Wiki) or someone who put enourmous
         energy into garbaging multiple pages. The {auther} field always
         contains at least an IP address to allow easy tracking of such
         activity, and this plugin just enables you to remove page versions
         whose {author} field matches a certain string (the attackers IP
         address).



         tools/index.html
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         If this page looks ugly, it is because you are using IE prior
         version 7 - it works fine with Mozilla, Opera and even text-only
         browsers like w3m. 



commandline tools/
ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
As opposed to the web based tools/ mentioned above, a few scripts in tools/
must be run from the commandline. That is, you need a standalone PHP
interpreter (/usr/local/bin/php) and shell access to your web server.

If you don't have shell access, you could write temporary wrapper scripts
(see the note for ewikictl), or use one of the emulation packages (or start
up a xterm on the server in absence of ssh access). A detailed description
is out of scope of this document.

UNIX users will find those tools very useful and handy, while they effort
additional work from Windows users. But then all those tools/ should run
on Win32 systems too, but you often want to create additional .bat files
to make this more user-friendly. There is for example a 'ewikictl.bat'
demonstrating this.



         tools/ewikictl
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         ewikictl integrates a lot functionality of the web based tools/,
         some of them less flexible and others more powerful than in the
         other tools. It, for example, allows to generate database backups
         automatically and is often easier to use. On the other hand it
         will be of little use if you don't have a shell account on the
         WebServer running your wiki (because most times one cannot make
         remote mysql server connections).

         The most important feature is to make backups using the 
         --backup switch:

             All pages from the database will be saved into backup files
             in the directory given by --dest (or if not given into
             './backup-<currentdate>').

             The --format of the backup files can be: plain, fast, flat
             or xml, meta, xmlmeta, sql, mysql. But remember that only
             the first three mentioned formats can be reinserted using the
             ewikictl utility.

             You really should give the --all parameter too, whenever you
             make a backup, because else only the very last version of each
             page will get saved (and think of a garbaged last version, this
             would be a bad idea). So USE --all ALLWAYS!

         Backups can be reread into the database using the 
         --insert switch:

             The --dest or --source parameter says where to search for the
             save page files, and the --format option again tells the
             correct backup format (you will get a garbaged database if you
             get it wrong).

             The --all option is of course necessary again if you gave it
             when doing the --backup, and ewikictl will complain if it
             believes the --all option was required.

             You can also use --insert to initially fill a database, or to
             add just a few new pages, as pages inside the database will
             never be overwritten by the ones added with --insert.

             The --insert switch also allows to be used to load just one
             file into the database.  --insert <WikiPageFileName>

         Another function is to speed up the database, by creating version
         --holes:

             If you utilize the db_flat_files and you have hundreds of
             versions for one page, things may get slow at some point of
             time, so you may wish to remove some of the unneeded versions.
             That is what the --holes is for, it strips some of the page
             versions from the database. Please keep in mind, that the
             very first version of each page may contain special control
             data, which is not available in the following ones (this is
             especially true for db_flat_files).

             Per default the 2nd version of a page until the 10th before
             the last page version will be removed. You can however specify
             this range yourself:
                 --holes 2..-10       (default)
                 --holes 5..-5        (5th until 5th before last version)

             Please also keep some versions at the end, as the very last
             one may contain mangled text (if someone backspaced around).

             The --all option is implied for --holes, but you can and you
             should combine --holes also with --backup. This special
             feature will save a backup into the --dest directory ('./holes'
             per default) before the page version is removed from the
             database.

         --format
             The default backup/insert format is the 'plain' one - which
             means just a pages content will be saved into the files.

             It is however recommended to use the "--format flat"  or
             "--format fast" instead, as both can contain the complete meta
             data of a page.             

         --ls
             Will print a directory-listing like list of all pages from
             the database.
             You can add a pagename as parameter, so only that one will
             get shown.

         --reset <pagename>
         --disable <pagename>
         --enable <pagename>
         --html <pagename>
         --readonly <pagename>
         --writable <pagename>
             Will set the according page flags for the given page. You can
             give the page name also by using the --page or --file or --id
             switch.

         --chmod <flags>
             Will set the page flags to the given decimal value. The
             pagename must be given using --page, --file or --id. This
             option of course requires knowledge of the flag/option values
             and their numeric/decimal representations.

         --unlink <filepattern>
             Can be used to delete a page. You can use the asterisk to
             remove more than one page, just an '*' would for example delete
             all pages.


         NOTE that you can also use this utility without a shell account on
         your WebServer, if you create temporary .php wrapper scripts, that
         contain nothing more than:
         <pre><?php  echo `./tools/ewikictl -ll`;  ?></pre>

         Please search google or freshmeat.net for one of those shell faking
         CGI scripts, to ease this, so can get the most out of ewikictl.



         tools/wiki2html
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Renders the WikiPages and saves the resulting <HTML> bodies into
         files. It currently cannot deal with images and binary content
         correctly.



         tools/mkhuge
         ŻŻŻŻŻŻŻŻŻŻŻŻ
         For lazy people - if for some reason your text editor does not
         allow to enter the correct include() commands for the files from
         the plugins/ directory you may find this shell script useful to
         create a monster version of ewiki (plugins and core script merged
         together into one file).
         See the paragraph about "monsterwiki.php" for more detailed infos.



         tools/mkpluginmap
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Is the companion tool for the new ewiki pluginloader extension. It
         traverses the plugins/ directories and generates a list which
         allows automatical loading of ["page"] and ["action"] plugins.

         Use the output of this script to replace the list of available
         plugins inside of the "pluginloader.php" script. But don't forget
         to disable that extensions, that you wouldn't like to be available.



         tools/mkpageplugin
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Can convert any StaticPage file (from the spages/ directory) into 
         a standard ewiki page plugin (to get included() like all the others
         then). It detects automatically the type of the given StaticPage
         input files - Wiki source (.txt), ready HTML content, or even PHP
         code.
         It's intended as help for the unexperienced PHP user, or if you
         needed to mass convert StaticPage files into plugins. But please
         note, that including() hundreds of page plugins slows down the PHP
         interpreter and eats a large amount of memory (and this was the
         reason for extracting some page plugins into StaticPages).



         tools/mkxpi
         ŻŻŻŻŻŻŻŻŻŻŻ
         The new .xpi plugins can be installed at runtime (password required),
         if the plugins/feature/xpi extension is loaded. This type of plugins
         however must be prepared first using the 'mkxpi' tool from their
         source scripts.

         A detailed description is available in the comment part of this
         commandline tool.



         tools/php5fix
         ŻŻŻŻŻŻŻŻŻŻŻŻŻ
         If you want to test ewiki with recent PHP5 beta versions, you
         either need to apply the fragments/php-patches/ or mangle the ewiki
         core script using the 'php5fix' commandline utility.

         It adds a few explicit typecasts, where this is known to be
         necessary to keep PHP5 versions happy.



         tools/collectplugins
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         Allows you to make a 'monsterplugin' script by analyzing your
         config.php script. It will output a combination of all activated
         plugins merged into one file, which you could afterwards glue
         together with the core script to get a real monsterwiki script.



examples/
ŻŻŻŻŻŻŻŻŻ
The file "examples-1.php" is the default layout, which you will see, when
you first run ewiki. The examples/ subdirectories now holds further example
'ewiki wrappers' or 'layout scripts' (commonly referred to as "yoursite.php"
scripts in the README).

There is not much further interesting stuff in here. If you can make a
contribution, just do (however, in the ewiki core tarball, we don't want
an image or graphics directory).



         examples/homepage.php
         ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
         This is an example on how to use ewiki.php with an authentication
         frontend. Note that this is not the recommended way to use a wiki
         (adding authentication can be considered "crippling" a wiki).

         "Authentication" means just a JavaScript based password query
         dialogue (the password is however checked server-side inside the
         homepage.src script).

         You should install it preferably as index.php as described on top
         of the file, the ewiki.php script must be there too. Edit the source
         and colours to suit your needs. Guess, it needs some images as well.



Pages in init-pages/
ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
This directory just contains text files with the wiki_source of the
initial pages, which are inserted if you start ewiki.php for the
very first time.
You can create these files with the tools/ewiki_backup.php script
or the 'ewikictl' commandline utility, what is very handy for backup
purposes or partial mirroring of all your content.

Using the "TextUpload" plugin/spage you can upgrade all of those
files that are already existing on your setup. You could also get
the latest tarball containing all default pages from
[http://ewiki.berlios.de/initpages/?MiniDump] to do so (TextUpload
can directly use that page tarball).


