The wiki in SCT allows you to generate PDF files on the fly from Wiki snips.

Please note tough, that this is still an experimental feature. It is quite resource expensive and might not be a good idea to be enabled on a high-traffic website.

1. General

The PDF generation works by taking the XHTML generated by the wiki (markdown) and use an XSLT to convert it into XSL-FO and finally generate a PDF out of this XSL-FO.

2. Requirements

So for this process, you will need an XSLT and XSL-FO processor.

• FOP - I would recommend FOP from apache which usually also contains an XSLT processor. This way we can generate PDFs using one simple command.

3. Configuration

By default PDF generation is disabled. You need to explicitly enable and configure it.

As all SCT configuration the settings are all defined in settings.py by modifying the SPH_SETTING dictionary. The following settings are supported:

3.1. wiki_pdf_generation

Supported Values: True, 'loggedin', 'staff', False

• True will enable PDF generation for all users
• 'loggedin' only for users which are loggedin
• 'staff' only to staff members
• Any other setting will disable PDF generation.

3.2. wiki_pdf_generation_command

Defines the command which is executed to convert the XHTML file into a PDF file.

A typical value can look like the following:

SPH_SETTINGS['wiki_pdf_generation_command'] = \
    'export PATH=/opt/java/bin:$PATH ; /opt/fop/fop -xml %(srcfile)s -xsl ' + \
    os.path.join(SCT_ROOT_PATH, 'sphenecoll', 'sphene', 'contrib', \
    'misc', 'xsl', 'xhtml2fo.xsl') + ' -pdf %(destfile)s '

This command makes quite a few assumptions, so you need to modify it. Here is a short explanation:

• First it adds the 'java' executable into $PATH
• It executes the fop shell script (which will execute java with FOP)
• It uses the XSLT file which is in the SCT release/repository (you can safely hardcode the path here.. if you have no SCT_ROOT_PATH pointing to the root of the SCT repository (the 'communitytools' directory, containing 'sphenecoll' & co)
• There are two settings which this string get replaced:
  • srcfile - this is the .xhtml file (the rendered body of the wiki snip)
  • destfile - the expected output file which will hold the .pdf file

3.3. wiki_pdf_generation_cachedir

This is the "cachedir" where generated PDF files (and .xhtml files) will be stored. (Default: /tmp/sct_pdf)

3.4. wiki_pdf_generation_static_filepath

For smileys to work (if you are including a board category in the wiki snip) you need to configure this setting. It should point to the static directory - communitytools/static/sphene within the SCT release / SCT repository.

4. Methods

The wiki snip contains a method 'pdf_enabled()' which will return True or False depending if PDF generation is enabled (for the current user).

An example usage would be (in a template like showSnip.html):

{% if snip.pdf_enabled %}<a href="{{ snip.get_absolute_pdfurl }}">Download PDF</a>{% endif %}

5. Considerations

The generation of PDF files using XSLT and XSL-FO is very performance expensive and can take a few seconds 100% CPU. Since PDF files are generated on the fly if they are not already cached (or if the wiki snip has changed since the last generation) - you should considering only enabling this feature for logged in users or staff.

6. Feedback

This is a experimental feature. So if you are planning on using it please let me know (in the board) what you think about it (performance and feature-wise), if it works for you - and how it could be improved - thanks.