Mediawiki collection extension installation

The educational technology and digital learning wiki
Jump to navigation Jump to search

Definition

The Mediawiki collection extension allows a user to organize personal selections of pages in a collection. Collections can be:

This page includes some centralized help links and installation tips made for our own use - Daniel K. Schneider 16:31, 4 May 2009 (UTC).

See also:

Help pages

Bugs and feature requests:

Help (can also be used for informal bug reports)

Information about the collection extension and related server-side software

Installing the whole suite requires some installation skills, but should go fairly smoothly on any Unix system and should be easy on a Debian-based Linux.

Collection extension installation

The collection extension installs like any other Mediawiki extensions. Really easy with Mediawiki=> 1.14 (Spring 2009).

(1) Installing

Get it from Extension:Collection on Mediawiki.org. E.g. with

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/Collection/

Read:

README.txt

You then can just leave all the defaults and the PDF will be generated by PediaPress. However, if you have a slow server like this one, you also should install a local render server (read the whole rest of this page, the pediapress server will likely loose pages due to server overload ....)

(2) Tuning

I suggest changing the file Collection.i18n.php and change the string.

'coll-rendering_text' => "<p><strong>Please wait while the document is being generated.
Depending on the size of book you may have to wait 5, 10, 15 minutes or longer.
</strong></p> 
 ......"

'coll-save_collection_text'       => 'Choose a storage location for your book and enter a name:',
(3) Permission

If you want users to be able to save and share collections, add these:

$wgGroupPermissions['user']['collectionsaveasuserpage'] = true;
$wgGroupPermissions['user']['collectionsaveascommunitypage'] = true;

or maybe:

$wgGroupPermissions['user']['collectionsaveasuserpage'] = true;
$wgGroupPermissions['sysop']['collectionsaveascommunitypage'] = true;
(4) Define templates

You should define the following (language-dependant) templates and categories:

  • Template:Saved_book (Grab a copy from a wikipedia and modify).
  • Category:Books
  • Category:Book tool (not really needed)

For conditional inclusion of text within articles you must define these templates (inspired from the french wikipedia, the English uses some parser extension which we probably should also install and test at some point - Daniel K. Schneider)

Template:Hide in print:

<includeonly><span class="noprint">{{{1}}}</span></includeonly>

Template:Only in print:

<includeonly><span class="hidden">{{{1}}}</span></includeonly>

Then, edit MediaWiki:Common.css and add the following CSS rule:

.hidden {display:none}

mwlib installation

Not needed if you have a fast server and want to use the pediapress server. Installation notes made for Solaris.

Prerequisites

Install these if don't have them (usually you do)

  • Python => 2.5
  • Perl => 5
  • g++
  • Latex

Install Blahtexml

  • (not done so far)

Install setuptools-0.6c9-py2.5.egg

sh setuptools-0.6c9-py2.5.egg

Install python imaging library (PIL)

 python setup.py install

Install odfpy 0.7.0 (not 0.8.0)

python setup.py build
python setup.py install

Install rec2c

pkgadd -d re2c-0.13.5-sol10-sparc-local 

Install ocaml

pkgadd -d ocaml-3.10.2-sol10-sparc-local

Mwlib

Mwlib can be installed from a tar ball, alternatively through mercurial with easy_install.

I had to install manually, since I wanted to make some light patches to the code.

Slowing down the page pulling

Problem: One ought to able to slow down the server. mw-render has an option for reducing threads. But no parameter can be set in the mw extension or the mwserver itself. Therefore, one has to build mwlib from source. Changes made:

OLD In older versions, it was possible to change file mwlib/options.py in about line 60, change the default for --num-threads, e.g. from 10 to 3 if your server couldn't cope. This is no longer possible, but the server now behaves in more nice way :) - Daniel K. Schneider 18:29, 16 June 2009 (UTC)

Not suported (unimportant) tags
  • Added in mwlib/tagext.py around line 100 a tag to exclude:
'pageby', 'uml', 'graphwiz', 'categorytree', 'summary'
  • Note: 'uml' and 'graphwiz' could be fixed by using the cached picture instead
Setup.py problem
  • none currently :)

Then go:

 python setup.py install

Alternative if you don't plan any changes

easy_install mwlib && rehash

Other libraries needed by mwlib

pygments
easy_install Pygments
Fribidi - both a library and the Python bindings
./configure --prefix=/usr/local
make
make install

(this is difficult to install)

 setenv fribidi_CFLAGS "-L/usr/local/lib -I/usr/local/include"
 setenv fribidi_LIBS -lfribidi
./configure
make
make install
Ploticus

(not installed)

mwlib.rl
easy_install mwlib.rl

Alternatively from a tarball:

texvc
  • Is in your mediawiki installation
  • Compile with gmake it if not already done (needs ocaml, see above)
cd /XXX/mediawiki/math
gmake
./texvc_test
  • Add the directory to the system path

Testing

mw-render --config=http://edutechwiki.unige.ch/mediawiki/ --writer=rl --output=./flash-cs3.pdf Flash_CS3_desktop_tutorial

mw-serv

MW Serv provides a server interface for the mw-render engine and mw-zip.

Run the server

mw-serve --cache-dir=/data/mwcache/mwlibcache/ --logfile=/data/mwcache/logs/mwserve.log --mwrender-logfile=/data/mwcache/logs/mwrender.log --mwzip-logfile=/data/mwcache/logs/mwzip.log --mwpost-logfile=/data/mwcache/logs/mwpost.log --mwzip-logfile=/data/mwcache/logs/mwzip.log

An init script

Create a user, e.g. something like

useradd -u 70002 -g 16100 -s /bin/sh -d /data/mwcache mwserv

Chown the cache and log directories to this user

chown -R mwserv mwcache/

/etc/init.d script

see the example at http://svn.wikimedia.org/viewvc/mediawiki/trunk/tools/mw-serve/mw-serve.sh Add it to appropriate run-levels with chkconfig (see man chkconfig)

Tuning and tips

See also some changes to the source code above.

Tweaking the collection extension

Add in Localsettings.php (if not already done) the rendering engines you will support. Typing mw-render --list-writers will list the ones you installed. E.g.

$wgCollectionFormats = array(
          'rl' => 'PDF',
          'odf' => 'ODT',
      );

Add in Localsettings.php if not already done the name and port of the server (altenatively you also could install a cgi script).

$wgCollectionMWServeURL = "http://xxx.yyy:8899";

Extra stuff:

For the license, make sure to give the correct RAW wiki URL. Or if this doesn't work, remove the line and the user will see a URL.

$wgLicenseURL = "http://edutechwiki.unige.ch/mediawiki/index.php?title=EduTech_Wiki:Copyrights&action=raw";

Limit to 100 articles:

$wgCollectionMaxArticles = 100;

Tips for creating wiki books

Creating a serious book

It is best just to "hand edit" a stored book. E.g. you may start by adding a category or isolated articles to a book with the collection interface, but once you got most of the articles:

  • Save the book
  • Then select it from the category:books and then just edit the page in the "normal way". The structure and syntax to respect is demonstrated by the following example:
{{saved_book}}
== My Book ==
=== Example ===
;Foo
:[[First article]]
:[[Second article]]
:[[Third article|This article renamed in the book]]
;Bar
:[[Fourth article]]
:[[Fifth article]]
:[{{fullurl:Sixth article|oldid=20}}Sixth article version:20]
[[Category:Books]]

Install the Mediawiki source extension

If you have articles that include computer source code (XML, ActionScipt or whatever), you also should install the source extension (CodeSyntaxHighlight MediaWiki for formatting computer code.

If you use XML within "pre" tags, the parser may become confused.

Also, the printed Pediapress book will look much prettier. Editing all your wiki pages may represent work, but user reading the on-line pages also will be grateful, colored and indented code is really much more readable !

Pictures and drawings

(1) Readjust some image sizes

(I'll have to be more precise about this, but I'll first need to analyze both a wiki book I got and the generated PDF...)

  • Don't use large pictures when smaller ones are readable
  • Create screendumps from smallest possible areas if you plan to show hairy details (see also the screen capture tutorial).

(2) Color Printed PDF is mostly grey (Pediapress books certainly are). E.g. when you create drawings or annotate images with text, you should make sure that shades of grey still allow to identify critical elements. A related very difficult issue is writing the text. Avoid writing about "blue" and "green" arrows and "green" or "yellow" dots ...

  • To select colors that show on gray printers, you may use a color scheme designer such as colorschemedesigner.com and simulate color vision deficiency with "full colorblindness". Else print your drawing, before you import to wiki.
  • A radical solution is to use gray images already upfront in the wiki. This way you are sure to get it somewhat right. Note: "grey" is spelled "gray" in CSS and X11.

Stuff that the parser doesn't handle well

As of mid May 2009 (so this may change)

  • Some extensions (like graphwiz) are not supported, see above. There is no solution for this, except not using these.
  • Some extensions that are not supported wont' matter, e.g. pageby. But you will have to modify the source code for filtering if you own your own server (see above) or file a request.
  • &nbsp; prints "as is", therefore avoid! Use ":" and "::" etc. to indent lines for example
  • Source code (either within "pre" or "source" tags that follow a picture will be printed over the picture. Probable reason. The renderer will reduce a picture and try to wrap text around it. Source code cannot be wrapped or not as well. Workaround: Move the image either 20 lines above or after the code.

Conditional inclusion/exclusion

Warning: This wasn't tested with Pediapress. If you plan to buy a book, use these on the very first pages, then have a look at the preview.

1) Exclude templates

You may exclude any template from the PDF generation you wish by adding them to the Category:Exclude in print. Use with care, since this will filter for all users !

2) Exclude certain specific content

By using Template:Hide in print, certain specific content, such as a few words or an image, can be excluded from printing.

This content will be printed.{{Hide in print|This content will not be printed.}}This content will be printed.

Alternative solution: use the class="noprint" within a div or span tag.

3) Include certain specific content only in print versions The Template:Only in print can be used to insert content that shall only be visible in offline versions.

Example: print this and display it in the browser {{Only in print|this is only in PDFs or printed books visible, not with the browser}} this is visible in the browser and in print as well.

Alternative solution: use the class="hidden" within a div or span tag.

4) Substitute templates

You can create a print version of a template under the name "TEMPLATENAME/Print" with TEMPLATENAME being the name of the original template.

(more to come ....) - Daniel K. Schneider 12:54, 20 May 2009 (UTC)