Note: The complete, current lists of commands are in the repository. The following page provides a brief introduction to the most significant tools of mwlib.

Note: During the fast development process, commands can change quick (quicker than this documentation).
All commands have a --help switch, that lists the up-to-date available commands.

mw-render

mw-render converts MediaWiki article(s) to multiple output formats.

Built-in mw-zip offers rendering to mwxml, XHTML 1.0 Transitional, DocBook XML or OpenDocument (Text). Rendering into PDF is possible too. To setup a environment for rendering into PDF, please visit the RenderToPDF page.

In addition, to specify the output format, you'll have to specify the input e.g. en.wikipedia.org. If you're not familiar with the versatile input formats, please familiarize yourself with the VirtualWiki-concept.

Examples:

  mw-render --list-writers

Lists the built-in output writers.

  mw-render -c :en -w odf -o nasa.odt NASA

Gets the article 'NASA' from the English Wikipedia ( -c :en is shortform for the BaseURL?) and write (-o /path/file.ext) it in the current working directory in the odf-format.

Maybe the long form is more readable:

  mw-render --config=http://en.wikipedia.org/w/ --writer=odf --output=./nasa.odt NASA

Maybe you'll need a login to your wiki, then append --login=USERNAME:PASSWORD to get access.

You can use a ConfigFile config file to swap the MediaWiki specific options to a file.

By default, mw-render grabs images too. Thus the traffic maybe become very large. To decrease the traffic, the -x flag (long: --no-images) suppresses the download of images.

Also you can resize the images with the flag: -i IMAGESIZE (long: --imagesize=IMAGESIZE). IMAGESIZE indicate the maximal lenght of the longer side in Pixel.

  mw-render -c :en -w odf -o nasa.odt -i 320 NASA

Gets the article NASA from the english Wikipedia, resizes the images to a mxixum of 320 pixel and renders it to odf-format.

Remember:

  mw-render --help

gives you a list of all features of mw-render.

mw-zip

mw-zip grabs all relevant information (articles, images, templates, etc) from a MediaWiki and puts them into a single Zip-file for further processing.

Examples:

  mw-zip -c :en -o tmp.zip Sun Moon Stars   

Gets three articles from the english Wikipedia and puts them in a Zip-file named tmp.zip in your current working directory.

By default, mw-zip grabs images too. Thus the Zip-files may become very large. For example, the articles Sun, Moon, and Stars generate a Zip-file of 16Mb size.
To decrease the size, the -x flag (long: --no-images) suppresses the download of images. (c.f.: size without images: ~500kb).
Alternatively you can resize the images using the flag: -i IMAGESIZE (long: --imagesize=IMAGESIZE). IMAGESIZE indicates the maximal length of the picture's (longer) side (in Pixel).

  mw-zip -c :en -o tmp-resize.zip -i 320 Sun Moon Stars   

Gets three articles from the english Wikipedia, resizes the images to a maximum of 320px and stores the data in tmp-resize.zip. (Now ~ 4,5MB)

Now its easy to render them, e.g. to a .odt-file:

  mw-render -c tmp-resize.zip -w odf -o sun_moon_stars.odt 

Note: If you omit the list of articles, mw-render renders all articles in the given source ZIP file.

Of course mw-zip supports the VirtualWiki-concept, therefore an different source than the Wikipedia site is accepted as well, e.g an other zip-file:

  mw-zip -c tmp.zip -i 240 -o tmp-resize-240px.zip     

Repacks all articles from tmp.zip to tmp-resize-240px.zip and resizes the image's longer side to maximal 240 pixel.

As mentioned above, the primary purpose of mw-zip is the further processing of sets of articles. For example, in combination with mw-render, you can render the articles on a application server later on. To support this scenario, the mw-zip command has a flag -p (long: --posturl=POSTURL) to POST a zipped set or articles to the specific URL.

The primary purpose of mw-zip targets on a print-on-demand service: You can use the -g flag (long: --getposturl) instead of -p to use the pediapress.com print-on-demand service:

  mw-zip -c tmp.zip -g

Uploads all articles in tmp.zip to the pediapress.com print-on-demand service. Warning: depending to your upload speed, this could take some time!

mw-serve

mw-serve provides a server interface for the mw-render engine and mw-zip. It accept orders via HTTP / fcgi / scgi / cgi.
The main task of mw-serve is to route the orders from the Collection Extension to the (pdf) renderer. For this reason, it is recommend to start mw-serve as a permanent service on your webserver.

Note__:Your own mw-serve is especially needed, if your wiki is not accessible from the Internet (that means for the public PediaPress render server too).
NOT accessible means:

• Your wiki running on a private address range, e.g. 192.168.0.0 and your firewall do not forward the requests and / or you do not have a valid domain name.

Examples:

  mw-serve --protocol=http --port=8899

Starts mw-serve on Port 8899 with the htt-protocol. This is the default.

  mw-serve -p 54322 -i 192.168.31.87

Binds the server to liston on a specific port (-p is short for --port) and a specific interface (-i is short for --interface).
Note that symbolic names like "eth0" are not supported.

  mw-serve --cache-dir=~/mytmp

Maybe the mw-render process have not write permission in the default cache directory /var/cache/mw-serve. You can use --cache-dir to change the location of the cache directory.
Other directorys/files, e.g. logfile can changed too. See mw-serve --help.

For the full list see commands.txt or mw-serve --help.

using mw-serve.cgi

Because many users havnt commandline access to theirs webspace, there is a cgi-script named mwlib.cgi that can be used as a CGI script equivalent for the mw-serve command.
Just copy the script to your executable directory (e.g. cgi-bin/) and adjust the configuration variables located at the top of the file. Remember to make the file executable with chmod.

For a complete setup to integrate the Collection Extension in your wiki with pdf rendering, see WikiToPDF.

If you have additional questions, please have a look in our mailing list.