mwlib.rl Developer Guide
This document describes the basic concepts of the pdf library mwlib.rl.
Prerequisites
Simple modifications, like changing fonts and their sizes, text justification etc. can be done without any programming knowledge.
Advanced modifications require python and probably mwlib and reportlab knowledge. The reportlab documentation can be found at [http://www.reportlab.org/os_documentation.html].
Module structure
mwlib/fonts/
All fonts that are used, are stored here. Additionally the built-in Adobe fonts STSong-Light (Simplified Chinese) and HYSMyeongJo-Medium (Korean) are currently used.
mwlib/rl/rlwriter.py
This is the main component. PDFs are built with the writeBook method of the RlWriter? object. Essentially an mwlib parse tree is transformed into reportlab objects and the rendered with reportlab.
mwlib/rl/rltables.py
helper functions for table layout and formatting.
mwlib/rl/pdfstyles.py
layout and style options are defined here. also the font registration and font switching is handeled here.
mwlib/rl/customflowables.py
custom reportlab flowables are defined here.
mwlib/rl/pagetemplates.py
page templates for reportlab are defined here
mwlib/rl/debughelper.py
some helper functions for debugging the parse tree and the reportlab object structure
mwlib/rl/apps.py
the applications that are built by the setup script are defined here
Main concepts
The following describes the main underlying concepts of the pdf library mwlib.rl.
The simplest way to generate a pdf is the mw-pdf application. First of all, an appropriate configuration file has to be created. A good starting point for that is the example configuration file example-mwlib.config (in the base directory). To generate a pdf simply type
mw-pdf -c YOURCONFIGFILE ARTICLENAME
where YOURCONFIGFILE is the config file that was just created and ARTICLENAME is the title of a mediawiki article in the configured Wiki.
RlWriter? Object (in mwlib/rl/rlwriter.py)
The RlWriter? object's central method is the writeBook method which generates a pdf from a metabook object. The metabook object contains the parse tree of the selected article (or collection). Each node in the parse tree is rendered with a corresponding write method of the RlWriter? object (e.g. node X is rendered with writeX).
Each write method should return a list of reportlab objects or a list of unicode objects.
Sensible page breaks
In order to achieve sensible page breaks elements are grouped together. The groupElements method takes headings and consecutive paragraphs and sticks them in a reportlab KeepTogether? flowable which tries to prevent pagebreaks.
Floating images
Images that have a right or left align property are put inside the textflow. The floatImages method collects images followed by paragraphs and sticks them in the FiguresAndParagraphs? flowable (mwlib/rl/customflowable.py).
Special Table handling (in mwlib/rl/rltables.py)
Tables need some extra handling, mainly because space in a pdf is limited in comparison to a browser window. Furthermore there are limitations in the table support of reportlab.
