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