paul@0 | 1 | Introduction
|
paul@0 | 2 | ------------
|
paul@0 | 3 |
|
paul@0 | 4 | The ExportPDF action enables the export of MoinMoin wiki pages as PDF
|
paul@0 | 5 | documents using XSLT, DocBook and XSL-FO external tools.
|
paul@0 | 6 |
|
paul@0 | 7 | Installation
|
paul@0 | 8 | ------------
|
paul@0 | 9 |
|
paul@0 | 10 | The following configuration settings are present in the ExportPDF.py module:
|
paul@0 | 11 |
|
paul@2 | 12 | PDF_EXPORT_MODE Indicates the tool to use
|
paul@2 | 13 | ("docbook", "wkhtmltopdf", "htmldoc")
|
paul@2 | 14 |
|
paul@2 | 15 | Depending on the above setting, the following settings may apply:
|
paul@2 | 16 |
|
paul@2 | 17 | For "docbook":
|
paul@0 | 18 |
|
paul@2 | 19 | XSLT_PROCESSOR Path to the xsltproc program
|
paul@2 | 20 | FO_PROCESSOR Path to the fop program
|
paul@2 | 21 | DOCBOOK_STYLESHEET_BASE Path to the directory containing DocBook resources
|
paul@0 | 22 |
|
paul@2 | 23 | Another setting that should not need modifying is the following:
|
paul@2 | 24 |
|
paul@2 | 25 | DOCBOOK_TO_FO_STYLESHEET Relative path to the docbook.xsl stylesheet file
|
paul@0 | 26 | from the DOCBOOK_STYLESHEET_BASE path (putting
|
paul@0 | 27 | them together should reference the file with an
|
paul@0 | 28 | absolute path)
|
paul@0 | 29 |
|
paul@2 | 30 | For "wkhtmltopdf":
|
paul@2 | 31 |
|
paul@2 | 32 | XVFB_WRAPPER Path to the xvfb-run program
|
paul@2 | 33 | WKHTMLTOPDF_PROCESSOR Path to the wkhtmltopdf program
|
paul@2 | 34 |
|
paul@2 | 35 | For "htmldoc":
|
paul@2 | 36 |
|
paul@2 | 37 | HTMLDOC_PROCESSOR Path to the htmldoc program
|
paul@2 | 38 |
|
paul@0 | 39 | Once configured, copy the ExportPDF.py module into your wiki's actions
|
paul@0 | 40 | directory.
|
paul@0 | 41 |
|
paul@0 | 42 | With moinsetup and a suitable configuration file (see "Recommended Software"
|
paul@0 | 43 | below), you can perform this last step as follows, with $EPDIR referring to
|
paul@0 | 44 | the ExportPDF distribution directory:
|
paul@0 | 45 |
|
paul@0 | 46 | python moinsetup.py -f moinsetup.cfg -m install_actions $EPDIR/actions
|
paul@0 | 47 |
|
paul@0 | 48 | Basic Usage
|
paul@0 | 49 | -----------
|
paul@0 | 50 |
|
paul@2 | 51 | Select the ExportPDF action from the actions menu. After choosing a paper/page
|
paul@2 | 52 | size, a PDF document should be offered for download.
|
paul@2 | 53 |
|
paul@2 | 54 | Choosing a Processor
|
paul@2 | 55 | --------------------
|
paul@2 | 56 |
|
paul@2 | 57 | The mode used in the action, indicated using the PDF_EXPORT_MODE setting,
|
paul@2 | 58 | determines which processor or processing toolchain will be used to generate
|
paul@2 | 59 | PDF documents. Different processors have different advantages and
|
paul@2 | 60 | disadvantages and these are summarised below.
|
paul@2 | 61 |
|
paul@2 | 62 | The "docbook" mode relies on Apache FOP which is a Java-based solution. This
|
paul@2 | 63 | obviously demands a functioning Java runtime environment, and the process of
|
paul@2 | 64 | setting up such an environment can be a chore. Moreover, the speed of the
|
paul@2 | 65 | resulting solution is not necessarily impressive, although the output is
|
paul@2 | 66 | better than the other processors.
|
paul@2 | 67 |
|
paul@2 | 68 | The "wkhtmltopdf" mode relies on a virtual X server and a WebKit-based tool,
|
paul@2 | 69 | and the installation of such packages is likely to be much more convenient if
|
paul@2 | 70 | they are available in your operating system distribution. The output suffers
|
paul@2 | 71 | from being generated from wiki page HTML and problems with the wkhtmltopdf
|
paul@2 | 72 | tool itself such as clumsy pagination.
|
paul@2 | 73 |
|
paul@2 | 74 | The "htmldoc" mode relies only on a single program, but this program does not
|
paul@2 | 75 | support UTF-8 content and also suffers from having to generate PDF output from
|
paul@2 | 76 | wiki page HTML.
|
paul@2 | 77 |
|
paul@2 | 78 | In summary, the "docbook" mode is by far the recommended solution.
|
paul@0 | 79 |
|
paul@0 | 80 | Recommended Software
|
paul@0 | 81 | --------------------
|
paul@0 | 82 |
|
paul@0 | 83 | See the "Dependencies" section below for essential software.
|
paul@0 | 84 |
|
paul@0 | 85 | The moinsetup tool is recommended for installation since it aims to support
|
paul@0 | 86 | all versions of MoinMoin that are supported for use with this software.
|
paul@0 | 87 |
|
paul@0 | 88 | See the following page for information on moinsetup:
|
paul@0 | 89 |
|
paul@0 | 90 | http://moinmo.in/ScriptMarket/moinsetup
|
paul@0 | 91 |
|
paul@0 | 92 | Dependencies
|
paul@0 | 93 | ------------
|
paul@0 | 94 |
|
paul@2 | 95 | The ExportPDF action has the following basic dependencies when used in
|
paul@2 | 96 | "docbook" mode:
|
paul@0 | 97 |
|
paul@0 | 98 | Packages Release Information
|
paul@0 | 99 | -------- -------------------
|
paul@0 | 100 |
|
paul@0 | 101 | xsltproc Tested with 1.1.26
|
paul@0 | 102 | Debian package: xsltproc
|
paul@0 | 103 | Source: http://www.xmlsoft.org/XSLT.html
|
paul@0 | 104 |
|
paul@0 | 105 | Apache FOP Tested with 1.0
|
paul@0 | 106 | Debian package: fop
|
paul@0 | 107 | Source: http://xmlgraphics.apache.org/fop/
|
paul@0 | 108 |
|
paul@0 | 109 | DocBook XSL Tested with 1.76.1
|
paul@0 | 110 | Debian package: docbook-xsl
|
paul@0 | 111 | Source: http://docbook.sourceforge.net/
|
paul@0 | 112 |
|
paul@0 | 113 | Java Tested with a Java 6 runtime
|
paul@0 | 114 | Debian package: openjdk-6-jre-headless
|
paul@0 | 115 | Source: http://www.oracle.com/technetwork/java/index.html
|
paul@0 | 116 |
|
paul@0 | 117 | The Java dependency is unfortunate and would ideally be avoided by using
|
paul@2 | 118 | something other than Apache FOP to convert XSL-FO content to PDF.
|
paul@2 | 119 |
|
paul@2 | 120 | When used in the "wkhtmltopdf" mode, the following dependencies apply:
|
paul@2 | 121 |
|
paul@2 | 122 | Packages Release Information
|
paul@2 | 123 | -------- -------------------
|
paul@2 | 124 |
|
paul@2 | 125 | wkhtmltopdf Tested with 0.9.9
|
paul@2 | 126 | Debian package: wkhtmltopdf
|
paul@2 | 127 | Source: https://code.google.com/p/wkhtmltopdf/
|
paul@2 | 128 |
|
paul@2 | 129 | xvfb Tested with 1.12.4
|
paul@2 | 130 | Debian package: xvfb
|
paul@2 | 131 | Source: http://www.x.org/
|
paul@2 | 132 |
|
paul@2 | 133 | When used in the "htmldoc" mode, the following dependencies apply:
|
paul@2 | 134 |
|
paul@2 | 135 | Packages Release Information
|
paul@2 | 136 | -------- -------------------
|
paul@2 | 137 |
|
paul@2 | 138 | htmldoc Tested with 1.8.27
|
paul@2 | 139 | Debian package: htmldoc
|
paul@2 | 140 | Source: http://www.htmldoc.org/
|
paul@0 | 141 |
|
paul@0 | 142 | Contact, Copyright and Licence Information
|
paul@0 | 143 | ------------------------------------------
|
paul@0 | 144 |
|
paul@0 | 145 | See the following Web page for more information about this work:
|
paul@0 | 146 |
|
paul@0 | 147 | http://moinmo.in/ActionMarket/ExportPDF
|
paul@0 | 148 |
|
paul@0 | 149 | The author of this packaging of the original work can be contacted at the
|
paul@0 | 150 | following e-mail address:
|
paul@0 | 151 |
|
paul@0 | 152 | paul@boddie.org.uk
|
paul@0 | 153 |
|
paul@0 | 154 | Copyright and licence information can be found in the docs directory - see
|
paul@0 | 155 | docs/COPYING.txt and docs/LICENCE.txt for more information.
|
paul@0 | 156 |
|
paul@0 | 157 | Release Procedures
|
paul@0 | 158 | ------------------
|
paul@0 | 159 |
|
paul@0 | 160 | Update the actions/ExportPDF.py __version__ attribute.
|
paul@0 | 161 | Change the version number and package filename/directory in the documentation.
|
paul@0 | 162 | Update the release notes (see above).
|
paul@0 | 163 | Tag, export.
|
paul@0 | 164 | Archive, upload.
|
paul@0 | 165 | Update the ActionMarket and ActionMarket/ExportPDF page.
|