1.1 --- a/README.txt Fri Nov 01 01:45:00 2013 +0100
1.2 +++ b/README.txt Fri Nov 01 15:21:36 2013 +0100
1.3 @@ -9,17 +9,33 @@
1.4
1.5 The following configuration settings are present in the ExportPDF.py module:
1.6
1.7 -XSLT_PROCESSOR Path to the xsltproc program
1.8 -FO_PROCESSOR Path to the fop program
1.9 -DOCBOOK_STYLESHEET_BASE Path to the directory containing DocBook resources
1.10 +PDF_EXPORT_MODE Indicates the tool to use
1.11 + ("docbook", "wkhtmltopdf", "htmldoc")
1.12 +
1.13 +Depending on the above setting, the following settings may apply:
1.14 +
1.15 +For "docbook":
1.16
1.17 -Another setting that should not need modifying is the following:
1.18 + XSLT_PROCESSOR Path to the xsltproc program
1.19 + FO_PROCESSOR Path to the fop program
1.20 + DOCBOOK_STYLESHEET_BASE Path to the directory containing DocBook resources
1.21
1.22 -DOCBOOK_TO_FO_STYLESHEET Relative path to the docbook.xsl stylesheet file
1.23 + Another setting that should not need modifying is the following:
1.24 +
1.25 + DOCBOOK_TO_FO_STYLESHEET Relative path to the docbook.xsl stylesheet file
1.26 from the DOCBOOK_STYLESHEET_BASE path (putting
1.27 them together should reference the file with an
1.28 absolute path)
1.29
1.30 +For "wkhtmltopdf":
1.31 +
1.32 + XVFB_WRAPPER Path to the xvfb-run program
1.33 + WKHTMLTOPDF_PROCESSOR Path to the wkhtmltopdf program
1.34 +
1.35 +For "htmldoc":
1.36 +
1.37 + HTMLDOC_PROCESSOR Path to the htmldoc program
1.38 +
1.39 Once configured, copy the ExportPDF.py module into your wiki's actions
1.40 directory.
1.41
1.42 @@ -32,8 +48,34 @@
1.43 Basic Usage
1.44 -----------
1.45
1.46 -Select the ExportPDF action from the actions menu; a PDF document should be
1.47 -offered for download.
1.48 +Select the ExportPDF action from the actions menu. After choosing a paper/page
1.49 +size, a PDF document should be offered for download.
1.50 +
1.51 +Choosing a Processor
1.52 +--------------------
1.53 +
1.54 +The mode used in the action, indicated using the PDF_EXPORT_MODE setting,
1.55 +determines which processor or processing toolchain will be used to generate
1.56 +PDF documents. Different processors have different advantages and
1.57 +disadvantages and these are summarised below.
1.58 +
1.59 +The "docbook" mode relies on Apache FOP which is a Java-based solution. This
1.60 +obviously demands a functioning Java runtime environment, and the process of
1.61 +setting up such an environment can be a chore. Moreover, the speed of the
1.62 +resulting solution is not necessarily impressive, although the output is
1.63 +better than the other processors.
1.64 +
1.65 +The "wkhtmltopdf" mode relies on a virtual X server and a WebKit-based tool,
1.66 +and the installation of such packages is likely to be much more convenient if
1.67 +they are available in your operating system distribution. The output suffers
1.68 +from being generated from wiki page HTML and problems with the wkhtmltopdf
1.69 +tool itself such as clumsy pagination.
1.70 +
1.71 +The "htmldoc" mode relies only on a single program, but this program does not
1.72 +support UTF-8 content and also suffers from having to generate PDF output from
1.73 +wiki page HTML.
1.74 +
1.75 +In summary, the "docbook" mode is by far the recommended solution.
1.76
1.77 Recommended Software
1.78 --------------------
1.79 @@ -50,7 +92,8 @@
1.80 Dependencies
1.81 ------------
1.82
1.83 -The ExportPDF action has the following basic dependencies:
1.84 +The ExportPDF action has the following basic dependencies when used in
1.85 +"docbook" mode:
1.86
1.87 Packages Release Information
1.88 -------- -------------------
1.89 @@ -72,7 +115,29 @@
1.90 Source: http://www.oracle.com/technetwork/java/index.html
1.91
1.92 The Java dependency is unfortunate and would ideally be avoided by using
1.93 -something other than Apache FOP.
1.94 +something other than Apache FOP to convert XSL-FO content to PDF.
1.95 +
1.96 +When used in the "wkhtmltopdf" mode, the following dependencies apply:
1.97 +
1.98 +Packages Release Information
1.99 +-------- -------------------
1.100 +
1.101 +wkhtmltopdf Tested with 0.9.9
1.102 + Debian package: wkhtmltopdf
1.103 + Source: https://code.google.com/p/wkhtmltopdf/
1.104 +
1.105 +xvfb Tested with 1.12.4
1.106 + Debian package: xvfb
1.107 + Source: http://www.x.org/
1.108 +
1.109 +When used in the "htmldoc" mode, the following dependencies apply:
1.110 +
1.111 +Packages Release Information
1.112 +-------- -------------------
1.113 +
1.114 +htmldoc Tested with 1.8.27
1.115 + Debian package: htmldoc
1.116 + Source: http://www.htmldoc.org/
1.117
1.118 Contact, Copyright and Licence Information
1.119 ------------------------------------------