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