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