PublishPDF

Summary: Typesets wiki page collections into PDF (finalist: New Zealand open source awards 2008)
Version: 2.2.47 (released 2016-01-06) -- see release notes, EPUB and DocBook output, custom book styles, book glossaries and minor fixes and improvements
Status: Stable, reliable and substantially complete, php 5.5 compliant
Prerequisites: tested and stable with pmwiki 2.2.56 and above, requires php 5.3 or above
Prerequisites: (if you are running a local Wikibook PDF server) Server 1.2.5 or above (available from http://www.wikipublisher.org/)
Maintainer: jr

Question

How can we use a wiki as a collaborative desktop publishing system, to generate publishing-quality books, e-books and other documents from any wiki page collection?

Why do we want to do this? Reading long documents on screen is still a poor substitute for reading the same content on paper. Word processor output is of higher quality than a printed web page, and the output of high end publishing software is better still. Using a wiki as a collaborative publishing environment ensures consistency of published output, allowing authors to focus on content rather than being distracted by presentation matters.

Answer

This recipe turns PmWiki into a book publishing platform. The PublishPDF library is being used to publish books, technical manuals, teaching materials and other long or complex documents. For an example of a book, see Richard Stallman's GNU Zealand 2009 Tour Transcripts.

For a description of how to use Wikipublisher as a book publishing platform, see How to Produce a Book.

The Wikipublisher.BasicFeatures.pdfΔ, produced from a standard PmWiki page, summarises and illustrates what the library offers. It typesets text, lists, tables, images and equations ready for printing. It provides citation markup to support bibliographies. See http://www.wikipublisher.org/ and give it a try.

Install the PublishPDF library

  1. download and expand wikipublisher-2247.tar.gzΔ (for PmWiki versions 2.2.55 and below, use wikipublisher-2241.tar.gzΔ)
    • this version is robust and stable under PmWiki 2.2.56 and above and does not use the /e qualifier
    • if you are running Wikipublisher and upgrading from PmWiki 2.1.27 to 2.2, please read Wikipublisher.UpgradingToPmWiki22
    • the EPUB creation is still beta, but is now stable enough for regular use (see also the Wikipedia EPUB article)
  2. browse through the sample Wikipublisher.UserGuide.pdf.zipΔ (100kB zipped; 184kB pdf) (generated using the wikipublisher library)
  3. move the skin directories from skins/ into pub/skins/
  4. move the pdf icons from images/ into pub/images/
  5. move the css files from css/ to pub/css/
  6. move the cookbook/wikipublisher/ directory into cookbook/
    • moving wikipublisher/ will move various scripts plus a latex/ directory into cookbook/
  7. add include_once("$FarmD/cookbook/wikipublisher/extensions.php"); to the start of local/config.php
    • you can override the default wikipublisher skin by setting $Skin = 'yourskin'; after the include
    • it's best to test wikipublisher with its default skin first
    • if using utf-8 encoding, set $XMLEncodingFmt = 'utf-8';
  8. disable MarkupExtensions, PageTableOfContents, PublishWikiTrail, RenamePage, SearchExtensions, WikiForms and WikiCalendar (all included in the PublishPDF recipe)
    • the versions included with wikipublisher are tested as a unit; use other versions at your own risk
  9. disable any of the DictIndex versions you may have installed (the PublishPDF version can be disabled if preferred; set $MarkupEnabled['titledictindex'] = 0;)
  10. register your site at http://www.wikipublisher.org/
  11. try a search -- you should see a PDF checkbox and a Publish button
  12. you may wish to disable one or more of the optional recipes -- pagetoc, rename, search, wikilog -- by setting $MarkupEnabled['recipe'] = 0; where 'recipe' is 'pagetoc', 'rename', 'search', or 'wikilog'

Now add (:typeset:) to a WikiTrail page. You should see a Typeset button and a PDF options link.

You can also run your own wikipublisher pdf server: InstallTheServer

To get help from (and in turn help) other users, join the DiscussionGroup.

Print any combination of wiki pages

The intent is to support a print run of one. Provide a one-click publishing button that can be added to any of the following:

  • a single wiki page
  • a trail page
  • selected stops on a trail
  • a search results page
  • a category page
  • a backlinks page (the links to the current page)
  • a links page (the links from the current page)
  • any other dynamic page list, such as WikiCalendar, WikiForms, and so on

For dynamic page lists, such as search results, the visitor can choose which pages to include in the output. Each page in the list has a checkbox to include it in the output.

Apply print-oriented styles

Pressing the publish button will typeset the selected pages in a form suitable for printing or distributing as a PDF. This includes:

  • a cover page
  • a summary page
  • a table of contents page
  • PDF bookmarks and metadata
  • internal cross-references (such as see page xx)
  • running headers and footers (including mirroring for duplex printing)
  • substituting high resolution versions of images, if these are available
  • auto-numbering of major headings
  • translating all wiki markups to their print equivalents
  • footnotes for references to external links
  • etc, etc, etc

Control print presentation

The information seeker has various options to change the look of the generated PDF. These include:

  • what the cover looks like (title, alignment, font, etc)
  • duplex printing
  • heading and body text styles
  • paper size
  • section numbering
  • watermark text

The print presentation options are defined in Site.Template pages (included in a wikilib.d/ with the distribution and automatically added to the list of page locations). The publishing options cascade:

  1. run-time publishing settings take first priority
  2. if no run-time settings, a Group.Template takes priority
  3. if no Group.Template, a Site.Template is used

There are different templates for typesetting a single page, a trail page, a calendar page, and a search results page. An administrator can edit these like any other wiki page, for example to translate the form options into a different language. These pages use the WikiForms markup syntax.

History

See the release log

  • 06 January 2016 -- 2.2.47 fixes a bug in php 5.5 support
  • 30 December 2012 -- 2.2.41 improves htmlprint and htmlpublish skins
  • 11 November 2012 -- 2.2.40 fixes calls to htmlspecialchars to pass the charset
  • 25 April 2012 -- 2.2.39 adds support for DocBook XML output
  • 13 December 2011 -- 2.2.38 adds support for local book.sty files to modify book layout
  • 31 October 2011 -- 2.2.37 adds support for glossary of terms and abbreviations
  • 08 May 2011 -- 2.2.36 enhance use of images in book front matter
  • 24 February 2011 -- 2.2.35 minor cosmetic improvements, mainly to book metadata
  • 27 January 2011 -- 2.2.34 improves treatment of book metadata, including extensible metadata
  • 18 December 2010 -- 2.2.33 minor maintenance release to improve indexing and citations
  • 26 November 2010 -- 2.2.32 minor improvements to quotations, dedications and blurb
  • 17 November 2010 -- 2.2.31 improves book indexing and adds "publisher's blurb" option
  • 10 November 2010 -- 2.2.30 fixes clash between pdf image substitution and pdf file inclusion
  • 09 November 2010 -- 2.2.29 adds new layout options and minor fixes
  • 15 October 2010 -- 2.2.28 adds epigraph support in book front matter
  • 09 September 2010 -- 2.2.27 cosmetic improvements for special characters
  • 25 August 2010 -- 2.2.26 adds new book page text variables
  • 13 August 2010 -- 2.2.25 provides more book layout options and support for including attached pdf files
  • 23 July 2010 -- 2.2.24 add support for book halftitle verso pages and layout enhancements
  • 12 July 2010 -- 2.2.23 improve support for multi-part books
  • 09 July 2010 -- 2.2.22 PDF support for head and headnr directives (PmWiki 2.2.11) and link titles (PmWiki 2.2.14)
  • 11 June 2010 -- 2.2.21 enhance tables, equations, page headers and footers, and PDF bookmarks
  • 17 May 2010 -- 2.2.20 expand range of styles for major section headings
  • 05 April 2010 -- 2.2.19 add support for multi-part figures (LaTeX subfigures)
  • 04 March 2010 -- 2.2.18 fix a bug in books with accented characters in the publisher name
  • 02 February 2010 -- 2.2.17 book enhancements and improve handling of (:markup:) directives
  • 16 December 2009 -- 2.2.16 update PDF options templates and minor display improvements
  • 27 September 2009 -- 2.2.15 improve book publishing with support for dedication, multi-part books and afterword
  • 28 August 2009 -- 2.2.14 improve handling of typographic quotes for languages other than English
  • 02 August 2009 -- 2.2.13 improve advanced table cells and increase control over date/time output
  • 09 July 2009 -- 2.2.12 add option to generate an envelope, use a poem as a book chapter aphorism, improve hyphenation of long urls
  • 14 April 2009 -- 2.2.11 improve support for 2 column layouts (wide tables and long urls)
  • 09 April 2009 -- 2.2.10 improves advanced table attribute support and adds new article layout options
  • 23 February 2009 -- 2.2.09 improves multilingual support and adds new book and article layout options
  • 01 January 2009 -- 2.2.08 enhances custom floats and supports width and align in advanced table cells
  • 02 November 2008 -- 2.2.07 enhances Fig, Tab and Div cross-references, if $ReferencePageNumbers = true;
  • 10 October 2008 - 2.2.06 enhancements to tables and cross-references to anchors
  • 23 June 2008 -- 2.2.05 minor enhancements to footnotes and monospaced text
  • 20 June 2008 -- 2.2.04 cosmetic enhancements to improve book and report layouts
  • 22 May 2008 -- 2.2.03 cosmetic enhancements to improve book and table layouts
  • 19 April 2008 -- 2.2.02 minor enhancements to table handler and some bug fixes
  • 10 March 2008 - 2.2.01 includes fixes to support PmWiki 2.2, adds a floating div option (treat a div like an image or table) and <hr> print style
  • 30 January 2008 -- 2.1.11 is tested with PmWiki 2.2beta65 and improves presentation of images and tables
  • 23 November 2007 -- 2.1.9 adds support for rotating images and tables
  • 06 November 2007 -- 2.1.8 maintenance release enhances equations, list styles; adds highlight, quotation markup
  • 10 October 2007 -- 2.1.7 maintenance release with minor enhancements, notably in handling of long Urls addresses
  • 20 September 2007 -- 2.1.6 a maintenance release that fixes minor bugs
  • 06 September 2007 -- 2.1.5 create and typeset letters, with addressee, subject, salutation, return address and so on
  • 04 July 2007 -- 2.1.4 improves support for citations and bibliographies
  • 09 May 2007 -- 2.1.3 adds support for citations and bibliographies
  • 23 March 2007 -- 2.1.2 is mostly a maintenance release, preparating for citation support
  • 07 December 2006 -- 2.1.1 tidies support for nested div markup and fixes minor bugs
  • 06 October 2006 -- 2.1.0 adds wikibook template
  • 20 July 2006 -- 2.0.9 various minor bug fixes and improvements
  • 11 July 2006 -- 2.0.8 support for figure and table cross-references, comment blocks
  • 27 May 2006 -- 2.0.7 improve treatment of headings
  • 12 May 2006 -- 2.0.6 minor improvements and bug fixes
  • 13 April 2006 -- 2.0.5 maintenance release that addresses minor bugs
  • 03 April 2006 -- 2.0.4 fix bug arising from whitespace markup in PmWiki 2.1
  • 01 April 2006 -- 2.0.3 minor feature enhancements and bug fixes
  • 06 March 2006 -- 2.0.2 add 2 column support and improve image logo support
  • 23 February 2006 -- 2.0.1 fix $EnableWikiStyles problem with pmwiki 2.1beta26
  • 21 February 2006 -- wikipublisher server released
  • 17 February 2006 -- 2.0.0 version released with PmWiki 2.1 compatibility
  • 02 February 2006 -- 2.0 beta 9 released, long table improvements, final beta, server-side to follow
  • 21 December 2005 -- 2.0 beta 8 released, more style improvements
  • 16 December 2005 -- 2.0 beta 7 released, improves wikistyle handling
  • 22 November 2005 -- 2.0 beta 6 released
  • 27 October 2005 -- 2.0.beta5 released
  • 07 October 2005 -- 2.0.beta4 released
  • 23 September 2005 -- 2.0.beta3 released
  • 12 September 2005 -- 2.0.beta2 released

Notes and Comments

  • This recipe is fully tested on PmWiki version: 2.1.27; there are no known remaining incompatibilities with the new features and changes introduced in PmWiki 2.2, as tested with version 2.2.0 beta 65. To use the Publish PDF library with the wikipublisher.org typesetting server, your wiki must be accessible over the web. To use it with a private wiki, you must set up your own local typesetting server. Recipe version 2.1.0 or above requires server version 0.9.4a or above. Recipe version 2.1.3 or above requires server version 0.9.5a or above.
  • Conflicts with cookbook recipes extendmarkup.php, extdictindex.php (includes its own version of these, tested with the pdf server). See also Wikipublisher/UpgradingToPmWiki22, for a discussion of pagelist and transition issues.

The recipe comes in 2 parts:

  1. a library of PmWiki scripts which instruct PmWiki to generate output using a print-oriented xml dtd; this includes suitable skins as well as replacements for the stdmarkup, wikistyles and other scripts -- these are installed as a PmWiki recipe
  2. a set of server scripts which transform the print-oriented xml output to a typeset pdf and download this to the reader's desktop -- these can be installed on any server anywhere (available from wikipublisher)

We have set up the pdf server as a web service and the PmWiki recipe points to it. An administrator only has to install the PmWiki recipe. An administrator may choose to run the pdf server software as well, for example to support publishing behind a firewall, or if the webserver uses a port other than 80 (our hosting service restricts outbound connections to port 80).

The main site is at http://www.wikipublisher.org/wiki. This is a working and fully-functional demonstrator.

So can i try it out? Where is the attachment? DirkBlaas

The first beta release is available now. The wikipublisher server is up and running; the code for the PmWiki recipe and server-side typesetting is complete and tested. The above Demo is stable and reliable. jr

I've tried it but it horribly nesses up me custom skin. even on standard pages. What should I do ?

Provide a url where we can have a look and expand on 'horribly messes up'. What is going wrong and what do you want to see happen? Are we talking about the logo? Wikipublisher uses a text logo (not an image) by default. Are we talking about what the pdf icon on every page does to the page? If so, this is what the library does by default. We insert $PageTypesetFmt into $HandleBrowseFmt ahead of $PageRedirectFmt. There is a p.pdf style that does 'float: right; margin-left: 8px;'. This puts the pdf icon into the top right hand corner of the page text. More information, please.

To be more precise, (and I know this is still a beta), the recipe seems to replace my custom skin with its own, which is not acceptable. Is there something that I am doing wrong ?

The recipe sets a default skin, very similar to the pmwiki default skin, which fully supports all wikipublisher features. It is a good idea to test your wikipublisher install with this skin first, to make sure it is working correctly. If you then add a $Skin = 'yourskin'; statement to local/config.php after the statement to include wikipublisher/extensions.php, your skin should load.

The following comments refer to the beta series of releases. The 2.1.x and 2.2.x series avoid these issues. jr

This seems to be a very interesting recipe, but there are a number of problems with it:

  • Installation: the list above (and on the site) is incorrect and not complete:
    • It contains a latex directory that does not seem to go anywhere
      • just move the wikipublisher/ directory into your cookbook/ directory; the wikipublisher/latex/ directory will move along with it -- it may not work if the latex/ directory is placed anywhere else
    • It seems to expect the scripts to go into a scripts directory in the cookbook, not a wikipublisher one.
      • no, it expects the scripts to go into cookbook/wikipublisher/ -- just move the wikipublisher/ directory into cookbook/
    • It is annoying to have to disable other extensions to run it. Why should they be included, especially if the version included is older ? It seems that the disabling option listed above for the DictiIndex actually works for most of them (like the calendar), if you look at the code. It would be nice to have the list.
      • the versions of recipes included are tested to work correctly as part of wikipublisher; sometimes, individual recipes move ahead, but the next wikipublisher release will catch up -- it's my intention that the preferred versions are those that make up wikipublisher, but at the moment we are in transition; it seemed better to include everything required to run wikipublisher, rather than asking people to download other recipes as well; check the documentation on how to disable the optional recipes -- see Wikipublisher.Recipes
  • It replaces my defined skin by its own. I can understand that for printing, it should do this, alright. But not for the consultation of the wiki.
    • The recipe sets a default skin, very similar to the pmwiki default skin, which fully supports all wikipublisher features. It is a good idea to test your wikipublisher install with this skin first, to make sure it is working correctly. If you then add a $Skin = 'yourskin'; statement to local/config.php after the statement to include wikipublisher/extensions.php, your skin should load. At a guess, your $Skin = statement fell before the wikipublisher include statement (fixed in version 2.0.5).
  • Although my site is registered on yours (newgallo.dnsalias.net), it still does not seem to work. I might have the firewall problem (see below), but it is not clear from the error message.
    • The server-side is available for download and local installation. When you make a pdf request from behind a firewall, pmwiki will try to visit a site (the wikipublisher server) that is not accessible. Presumably, the web server running pmwiki then issues some kind of error message. Is there a way that we can detect you are behind a firewall and issue a more suitable error?

In any case, I have disabled it for now, but I very much look forward to see the improvements.

Thank you for this excellent feedback. I hope the above responses are helpful and clarify matters. jr

I've installed the software as described but I'm behind a firewall and it doesn't work. Think I need the 'server-side' pdf convertion software - where can I get this from? Smc

If you are behind a firewall, then the typesetting server can't request the xml from your web server. There may be some things you can do to allow your pmwiki server to communicate with the typesetting server through the firewall. You'd need to discuss this with your technical staff. The server side software relies on a number of prerequisites (for example, I believe Debian Linux includes most of what you need):

  • Latex
  • ImageMagick
  • an xslt processor, such as Libxslt or Saxon (we found this was quite slow)
  • access to your own PmWiki approved url page

You may wish to test the pdf service on a public web site first, rather than going to a lot of effort setting up a server and then perhaps finding that it's not suitable for your needs. We haven't yet documented the server-side install process, so some patience and perseverence will be needed. Send an email to the pmwiki discussion list or directly to John Rankin (address in the software readme file) and we'll work out the best approach. Can you describe your operating environment in a bit more detail? jr

John, thanks for your response. Very interested in pursuing the server-side installation. Our company does not permit external public systems from accessing our internal network and documents. I've been tracking your project for a while as it seems to have the edge on other variants with it's intelligent mining of information (e.g. Wiki trail) and the high quality visualisation enhancing readability. This is why I feel its worth investing set-up time in this. I would be forced to setup an end-to-end solution from within the confines of our intranet to ensure no document 'left' our building. As you suggest, I'll contact you on the news group to see how we can proceed on this. Smc

The server software is sufficiently robust for people who want to give it a try, available from Wikipublisher.InstallTheServer. jr
  • Comment: i've just installed it (the server), works nice, but i have some problems :/
 Q: How to make it use only localhost communication?
What does this question mean? What is the set-up and behaviour is wanted?
 Q: How to make it include pmwikidraw ?
You need a publishing markup rule that re-interprets the draw files as regular Attach: ... .gif directives, I think. See Issues.00063.

Is it possible turn off linking to web sites in the generated PDF file?

Yes. This is controlled with PmWiki's standard link format variables. Url link customisation will be documented at Wikipublisher.Customise "soon". By default, links to external web sites are shown as page footnotes. This can be changed to omit the footnotes, using the variable $UrlLinkTextFmt. For example, in local/config.php, after including the wikipublisher library, set:

    if ($format=='pdf') $UrlLinkTextFmt = '$LinkText';

How can I make wikipublisher honour the LiteralWhiteSpace recipe (whitespace.php)?

Wikipublisher generally removes html output by other recipes that are not part of Wikibook XML. But it is possible to handle internal pmwiki tags such as <:vspace> before the whitespace recipe replaces it with its own style definitions. For example, to preserve every new line in wiki markup as an empty line (vertical space) in the pdf, use the following line in config.php, after including the wikipublisher extensions.php but before including whitespace.php:

  if ($format=='pdf') Markup(':vspace', 'fulltext','/<:vspace>/',"<tbook:p skip='med'> </tbook:p>");

For more or less vertical space per empty line use big or small instead of med. Frank

How can I use an unobtrusive page action link "PDF" instead of the Acrobat logo and the options button on every page?

To remove logos, checkboxes and buttons in your layout state in config.php, before including the wikipublisher extensions.php:

  $PageTypesetFmt = $PDFTypesetFmt = $PDFOptionsFmt = $PDFCheckboxFmt = '';

In your Site/PageActions you could either simulate the options button by adding

* [[{$PageUrl}/?n={*$FullName}&action=texprint| PDF]]

or simulate the Acrobat icon that leads to the download/e-mail/debug page with

* [[{$PageUrl}/?n={*$FullName}&action=print&ptype=print&format=makepdf| PDF]]

or even a direct link to the pdf by the wikibook rendering server, e.g.:

* [[http://www.wikipublisher.org/cgi-bin/mkpdf.pl/{$PageUrl}/?n={*$FullName}&action=printprint&format=pdf&ptype=print&surtitle=MySurtitle&title=MyTitle&subtitle=MySubtitle&pagesize=A4&duplex=on&autonumber=0&toc=on&sectionnewpage=on&ucsection=on&headingstyle=sans&parasep=indent&justification=on&bodystyle=serif&hrstyle=105&fontset=pslatex&fontsize=11pt&imagesize=regular&floathere=off&cfloatstyle=plaintop&cfloatname=Excerpt&wpversion=2002015&email= | PDF]]

To find out your url parameters, submit your preferences once via the options button, then choose download and copy the url that is visible in your browser during the processing, thus before wikibook has returned your pdf. Beware: Big documents can cause a timeout error, and the direct link doesn't provide users with an e-mail option! Frank

See Also

GeneratePDF is a light and simple alternative. The key difference between PublishPDF and most other PDF PmWiki recipes is that PublishPDF typesets the page collection; it doesn't just convert the HTML output to PDF.

Cookbook /
BackupHTMLZip  Export your wiki to static HTML then optionally compress/zip it (Experimental)
EPUBCreation  Assembles wiki page collections into an EPUB e-book file (EPUB output is ready for beta testing)
ExportHTML  Export PmWiki pages as "static" HTML pages
ExportHTMLWiki  Create a wiki using static HTML pages as front end for visitors (stable)
PmWiki2PDF-v2  Generate a PDF (Stable)
PrintGroup  Export WikiGroup pages to one large HTML file, and/or to PDF (Experimental)
PublishWikiTrail  Provide the ability to publish the pages of a wiki trail as a single web page, formatted for printing
SiteDump  creates a .tar.gz file of the complete site for download (stable)
WikiConversion  Recipes for converting other wikis from and to PmWiki
ZipExport  Export the content of PmWiki-formatted page files in a zip archive (Beta)

Contributors

jr

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.