WorkingWiki/Downloading and Installing WorkingWiki
From projects
Contents |
Requirements
WorkingWiki is an extension for the MediaWiki system, so the main requirement is a running MediaWiki wiki on a Unix-based server. (It's probably possible to run WW on a Windows platform, but it wouldn't be easy.) You will probably need shell access to the server.
WorkingWiki runs on MediaWiki 1.13. There are sometimes bugs in WW in more recent versions of MediaWiki. Once we upgrade the lalashan wiki installation, this should stop being a problem.
Executables
In order to use the WorkingWiki extension, you'll need to have make, latex, latexml, perl, and ImageMagick installed on the server, and whatever other executables you'll want to use on the project files (R, maxima, octave, sage, ...). Make, latex, perl, and imagemagick are common packages, and latexml can be installed from its website.
You also need a C compiler for one step of the installation process. It's only been tested with GNU cc.
The exporting features require version 1.20 or greater of GNU tar.
Helper extensions
It's also recommended to install the SyntaxHighlight_GeSHi MediaWiki extension, for source highlighting. [And to copy and paste these r.php and make.php files into its directory of language files, if they haven't been included with the extension.]
Downloading
Let's say the source code is to be installed in location /ABC/WorkingWiki/. (Typically /ABC is the extensions directory in your MediaWiki installation.)
Get the WorkingWiki sourcecode, either by downloading it as a package or via Subversion.
Downloading a package:
Get the latest .tar.gz from the sourceforge downloads page, and unpack it into /ABC.
Downloading from the Subversion repository:
cd /ABC svn checkout svn://svn.code.sf.net/p/workingwiki/code/trunk WorkingWiki
Installing
Add it to LocalSettings.php
The key step is to add
require_once('/ABC/WorkingWiki/WorkingWiki.php');
to your wiki's LocalSettings.php file or something included by it. This causes the wiki to include WorkingWiki as an extension.
The cache directory
Before you can use WorkingWiki, you also need to assign the directory where the project working directories will be stored. Let's call that location /XYZ. On lalashan, /XYZ is /var/cache/projectengine. (This is because WorkingWiki includes a separate component called ProjectEngine that manages the cache.) /XYZ should be outside of the webserver's directory, to avoid possible security issues where the working files could become visible to web visitors who aren't supposed to have access to wiki data. Include a line
$peCacheDirectory = '/XYZ';
in your LocalSettings file, after the above require_once command.
The default value of this variable is set in ProjectEngine/ProjectEngine.php. There are many other settings in there, as well as in WorkingWiki.php, that you can override the same way.
The custom namespace
WorkingWiki adds the ProjectDescription: namespace to your wiki. By default it uses namespace index 230 (and 231 for ProjectDescription_talk). If namespaces 230 and 231 are in use on your wiki, you'll want to define the constant NS_PROJECTDESCRIPTION before the require_once, setting it to an even number that isn't in use.
Compile the custom make executable
Now there is one remaining step in WorkingWiki:
cd /ABC/WorkingWiki/ProjectEngine; make
This step creates the pe-make executable that WW (actually ProjectEngine) uses to execute its make jobs. After doing this, make sure pe-make is executable by the web server, either by making sure it's executable by everyone:
chmod a+x pe-make
or by using chown to make its owner or group match the userid that runs the web server (often either apache or www-data).
MediaWiki configuration
The following MediaWiki settings changes are suggested, though they are not necessary:
$wgFileExtensions[] = 'eps';
- Add eps to the list of allowed file types for uploading. If you're likely to use pdflatex with .pdf files for figures, you'll want to enable uploading those files as well:
$wgFileExtensions[] = 'pdf';
- You may want to add 'ps' and other types as well.
$wgStrictFileExtensions = false;
- Allow file types to be uploaded when they aren't on the official list (there'll be a warning, but it'll be allowed).
$wgCapitalLinks = false;
- By default, MediaWiki automatically converts page names to make them start with a capital, which is useful for Wikipedia articles, but depending on how you're planning to use your wiki, might not be desirable. Setting this to false disables that feature. WorkingWiki should work fine whether this variable is true or false. Caution: if you change this setting when your wiki already has some content, you may need to run cleanupCaps.php to fix all the links and templates that have been working but are now broken, because of case sensitivity. Even once you do that, you may end up with a lot of awkward lowercased page names that you didn't want. Make sure to take a backup if you decide to do this to an existing wiki. See http://www.mediawiki.org/wiki/Manual:$wgCapitalLinks for info.
$wgUseTex = true;
- This enables the
<math>tag, which we don't necessarily care about, but it also enables the Preferences form where you choose to allow MathML output, which we do want. WW actually sets$wgUseTexto true for you, but make sure yourLocalSettings.phpdoesn't set it back tofalseafterward. [Note: this is only needed MediaWiki 1.17 and older: see below for differences in the 1.18 version.]
PHP configuration
Consider also raising the maximum length of a form entry allowed by the Hardened-PHP configuration, if you have the suhosin module installed with your php installation, because when people can write LaTeX articles on this thing, they'll want to write long ones. The default value is 65000 characters. On lalashan, this setting is in /etc/php.d/Z98_suhosin.ini.
suhosin.post.max_value_length = 2000000 suhosin.request.max_value_length = 2000000
Changes in MediaWiki 1.18
In MediaWiki 1.18, the math tag and associated features are split out into an optional "Math" extension. This means that WorkingWiki can not necessarily piggyback on its "Use MathML if available" preference setting. As a result, there are two different ways it can work: it can use the Math extension's preferences if the Math extension is installed in the wiki, or it can use its own "Use MathML when browser is compatible" preference setting.
By default, it adds its own setting to the preferences page when it detects that it's running in MediaWiki 1.18 or greater. However, it honors both versions of the preferences, so if you are running a wiki with the Math Extension you can also use that setting. To disable WorkingWiki's redundant preferences entry in that case, set $wwProvideMathmlPreference = false.
[Note: if you prefer not to enable the Math features in earlier versions of MediaWiki, it should work okay to set $wwProvideMathmlPreference = true instead, now that we have that feature. I haven't tested that.]
[Note also: WW now uses MathJax to display math content, so this preference is less important than it used to be. It's now used to tell WW that it can skip using MathJax, to save time, when you're running on a compatible browser.]
Upgrading to MW 1.18
When upgrading from an earlier version to MediaWiki 1.18 without the Math extension, users' MathML preference will be lost and they'll have to set the new preference value. There may be a way to use userOptions.php to set the new value based on the old value, or it can be done directly in MySQL. It's also possible to set a default value for the new setting using $wgDefaultUserOptions.
Support, Bugs, and Community
Consider joining the workingwiki-users email list, to be notified of updates and major bug fixes, and to share advice with other users and admins.
Bugs are best reported at the WorkingWiki bug tracker at sourceforge.net, though they can also be sent directly to the author/maintainer.
