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