Generate PDF Add-On

Generate a PDF from a single Foswiki page

Usage

• The simplest way to activate PDF printing, is to add genpdf to front of the SKIN setting. This will replace the PatternSkin 'Print Version' action with 'Generate PDF'
  • eg Set SKIN=genpdf,pattern
• A page can also be published by substituting genpdf for view in the topic URL.
• To make it even easier for novice Foswiki users to use, we added a link (like edit and attach) to our view.tmpl to publish the current page (using the current topic as the document title). The line we added to our template is:
  • <a href="%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdftitle=%TOPIC%">PDF</a>
• You may also choose to replace the Printable (?skin=print) targets in your favourite skin with

[[%SCRIPTURL{genpdf}%/%WEB%/%TOPIC%][Printable]]

• You can now generate a PDF document containing all of the descendents of the base topic as separate chapters. For example, if you create a ParentTopic, then create FirstChild and SecondChild with ParentTopic as their parent topic, then create GrandChildOne with FirstChild as its parent (and so on), you get a tree like this:

ParentTopic
   - FirstChild
      - GrandChildOne
      - GrandChildTwo
   - SecondChild
      - GrandChildThree

If you add '?pdfrecursive=on' to the URL parameters, all of the topics will be rolled into the PDF.

Configuring the Script

The script can be configured either via URL parameters or web preference variables. URL parameters have precedence over web preference variables. If neither of these are present, the script will use hard-coded default variables. The general script configuration variables are explained in the next section while header/footer and title page configuration are explained in subsequent sections.

General Configuration

The following table shows the various configuration variables and their meaning. The first column gives the variable to use if passed in the URL. The second column shows the variable to use if using a Foswiki preference variable (i.e. Set VARIABLE = ). The third column gives the default value if neither the URL nor Foswiki preference variable is used. Note that URL variables have precedence over Foswiki preference variables. For a more detailed description of the HTMLDOC related variables, see the HTMLDOC documentation at http://www.htmldoc.org.

URL Variable	Foswiki Preference Variable	Default Value	Example	Explanation
pdfbanner	GENPDFADDON_BANNER		Foobar Documentation System	Used to override the banner of a title page.
pdftitle	GENPDFADDON_TITLE		Writing Foobars
pdfsubtitle	GENPDFADDON_SUBTITLE		A short guide to creating foobar documents
pdfheadertopic	GENPDFADDON_HEADERTOPIC		GenPDFHeaderFooterTopic	The name of a topic that defines headers and footers using <-- HEADER LEFT "foobar" --> syntax
pdftitletopic	GENPDFADDON_TITLETOPIC		GenPDFTitleTopic	The name of a topic that defines the layout of the title page
pdftitledoc	GENPDFADDON_TITLEDOC			The name of an attachment of pdftitletopic; if specified ,becomes the title page. Allows images - see htmldoc manual
skin	GENPDFADDON_SKIN	pattern	nat	Default skin to use for PDF generation
cover	GENPDFADDON_COVER	print	print.nat	Default cover to use for PDF generation
pdfrecursive	GENPDFADDON_RECURSIVE	undef	on	Include children of the base topic in the PDF
pdfformat	GENPDFADDON_FORMAT	pdf14	pdf12	HTMLDOC output format
pdftoclevels	GENPDFADDON_TOCLEVELS	5	3	Number of levels to include in the PDF table of contents (use 0 to disable the generation of a table of contents). Note that HTMLDOC generates a table of contents based on HTML headers in the page.
pdfpagesize	GENPDFADDON_PAGESIZE	a4	letter	The page size for PDF output
pdforientation	GENPDFADDON_ORIENTATION	portrait	landscape	The page orientation (e.g. landscape or portrait)
pdfwidth	GENPDFADDON_WIDTH	860	1060	The pixel width of the browser (used to scale images--images wider than this will be truncated)
pdfheadershift	GENPDFADDON_HEADERSHIFT	0	+3	Shift all headers up or down (for negative values) by this amount (e.g. H1 would become H3 for a value of 2).
pdfkeywords	GENPDFADDON_KEYWORDS	%FORMFIELD{"KeyWords"}%	'foo, bar, baz, zip'	Used for PDF Keywords META info to help search engines
pdfsubject	GENPDFADDON_SUBJECT	%FORMFIELD{"TopicHeadline"}%	'Foobar document creation'	Used for PDF Subject META info to help search engines
pdftocheader	GENPDFADDON_TOCHEADER	...	l..	See http://www.htmldoc.org/
pdftocfooter	GENPDFADDON_TOCFOOTER	..i	.i.	See http://www.htmldoc.org/
pdfheader	GENPDFADDON_HEADER		.1.	Specify content of header, see http://www.htmldoc.org
pdffooter	GENPDFADDON_FOOTER		.1.	Specify content of footer, see http://www.htmldoc.org
pdfheadfootfont	GENPDFADDON_HEADFOOTFONT		Helvetica-Bold	Font specification for headers and footers.
pdfheadfootsize	GENPDFADDON_HEADFOOTSIZE		12	Sets the size of the header and footer text in points (1 point = 1/72nd inch)
pdfbodyimage	GENPDFADDON_BODYIMAGE			The image that will appear tiled in the background of every page
pdflogoimage	GENPDFADDON_LOGOIMAGE			The logo that will appear in a header or footer if you specify 'l' in the string (see http://www.htmldoc.org)
pdfnumberedtoc	GENPDFADDON_NUMBEREDTOC	undef	True	Option flag for getting numbered headings and Table of Contents. Set it to anything for true.
pdfduplex	GENPDFADDON_DUPLEX	undef	True	Option flag to set up the document for duplex printing. Headers and footers will swap position on alternating pages. Set it to anything for true.
pdfpermissions	GENPDFADDON_PERMISSIONS	undef	print,no-copy	PDF Security permissions to disable print/copy etc. By default the PDF is not protected.
pdfmargins	GENPDFADDON_MARGINS	undef	top:0.5in,bottom:2.5cm,left:12pt,right:15mm	Specify the page margins (white space to edge of page)
pdfbodycolor	GENPDFADDON_BODYCOLOR	undef	#CCff99	Specify the background colour of all pages
pdfstruct	GENPDFADDON_STRUCT	book	webpage	use book for structured topics, i.e. when rendering a bunch of topics recursively; use webpage when printing a topic without a specific heading structure, i.e. if it is just a normal webpage or if it has got a special VIEW_TEMPLATE
pdfcopyright	GENPDFADDON_COPYRIGHT	%WEBCOPYRIGHT%	Copyright 2009	Should PDF Metadata include the Foswiki %WEBCOPYRIGHT% or another value. If set to 0, copyright is excluded. If set to any other string, the string is included in the metadata. Htmldoc has a bug and appends the copyright to the author metadata, which can break some document management systems that depend on the metadata. Set to 0 to exclude the copyright from the PDF metadata.
pdfdebug	GENPDFADDON_DEBUG	0	1	Include debug messages and don't clean up temporary files after execution
pdffirstpage	GENPDFADDON_FIRSTPAGE	toc		First page viewer will open: toc table of contents; p1 first page; c1 first chapter.
pdfdestination	GENPDFADDON_DESTINATION	view		Output to browser window or save-as prompt
pdfpagelayout	GENPDFADDON_PAGELAYOUT	single		View's initial presentation layout: single, one, twoleft, tworight
pdfpagemode	GENPDFADDON_PAGEMODE	outline		Viewer's initial presentation mode: outline, document, fullscreen

If using Foswiki preference variables, copy them to the appropriate web preferences page. This plugin does not read settings from this topic!

• Settings for the GenPDFAddOn Plugin
  • #Set GENPDFADDON_BANNER =
  • #Set GENPDFADDON_TITLE =
  • #Set GENPDFADDON_SUBTITLE =
  • #Set GENPDFADDON_HEADERTOPIC =
  • #Set GENPDFADDON_TITLETOPIC =
  • #Set GENPDFADDON_TITLEDOC =
  • #Set GENPDFADDON_SKIN =
  • #Set GENPDFADDON_COVER =
  • #Set GENPDFADDON_RECURSIVE =
  • #Set GENPDFADDON_FORMAT =
  • #Set GENPDFADDON_TOCLEVELS =
  • #Set GENPDFADDON_PAGESIZE =
  • #Set GENPDFADDON_ORIENTATION =
  • #Set GENPDFADDON_WIDTH =
  • #Set GENPDFADDON_HEADERSHIFT =
  • #Set GENPDFADDON_KEYWORDS =
  • #Set GENPDFADDON_SUBJECT =
  • #Set GENPDFADDON_TOCHEADER =
  • #Set GENPDFADDON_TOCFOOTER =
  • #Set GENPDFADDON_HEADER =
  • #Set GENPDFADDON_FOOTER =
  • #Set GENPDFADDON_HEADFOOTFONT =
  • #Set GENPDFADDON_HEADFOOTSIZE =
  • #Set GENPDFADDON_BODYIMAGE =
  • #Set GENPDFADDON_LOGOIMAGE =
  • #Set GENPDFADDON_NUMBEREDTOC =
  • #Set GENPDFADDON_DUPLEX =
  • #Set GENPDFADDON_PERMISSIONS =
  • #Set GENPDFADDON_MARGINS =
  • #Set GENPDFADDON_BODYCOLOR =
  • #Set GENPDFADDON_STRUCT =
  • #Set GENPDFADDON_COPYRIGHT =
  • #Set GENPDFADDON_DEBUG =
  • #Set GENPDFADDON_FIRSTPAGE =
  • #Set GENPDFADDON_DESTINATION =
  • #Set GENPDFADDON_PAGELAYOUT =
  • #Set GENPDFADDON_PAGEMODE =

Limiting the PDF Generation Region

The add-on allows the user to define the region of the topic that should be included in the PDF generation (much like the Foswiki %STARTINCLUDE% and %STOPINCLUDE% variables. In this case, HTML comments are used instead. Everything between these two comments will be included in the PDF generation. The rest of topic will be excluded.

• Use <!-- PDFSTART --> to mark the starting point in the topic for PDF generation.
• Use <!-- PDFSTOP --> to mark the stopping point in the topic for PDF generation.

Note that there can be multiple PDFSTART and PDFSTOP comment pairs in a single topic to selectively include/exclude multiple sections of the topic in the PDF document. (If you view this page in raw mode or edit it, you'll see an example of multiple PDFSTART/PDFSTOP sections to exclude the Foswiki table of contents). If no PDFSTART/PDFSTOP comment pair appears in the topic, the entire topic text is used. In general, this should not be a problem except for title topics that include forms as the form meta-data will show up in a fairly illegible manner at the end of the document. Therefore, for topics that reference forms, a PDFSTART comment should be placed at the beginning of the topic and a PDFSTOP should be placed at the end.

NOTE: all %META: tags are removed from the base topic. If you want to display form data, you should add %FORMFIELD{"field"}% tags to the topic or title topic.

Creating and Configuring a Title Page

The add-on allows the user to use a topic as a title page for PDF generation. Earlier versions of the add-on required that the title page be expressed using pure HTML as the title page topic was not Foswiki rendered. The latest version of add-on, however, does full Foswiki rendering of the title topic page like any other Foswiki topic. In addition, the following variables can be passed with the URL to override their settings elsewhere (e.g. in the web preferences or Foswiki preferences pages).

Also note that the PDFSTART and PDFSTOP HTML comments should be placed at the beginning and end of title topic. An example title page can be found at GenPDFExampleTitleTopic.

Creating and Configuring Headers and Footers

The add-on also allows the user to configure header and footer formats for both the main section of the document and the table of contents. Configuring the main header and footer is much like configuring a title page. You can select a Foswiki topic to use for the header and footer. Remember to wrap the HTML comments that HTMLDOC uses for the header and footer between <!-- PDFSTART --> and <!-- PDFSTOP --> tags. The add-on will perform Foswiki common variable substition within the HTMLDOC header/footer HTML comments. This will allow Foswiki variables (such as %REVINFO{web="%WEB%" topic="%BASETOPIC%"}%) to be embedded in the headers and footers.

See the HTMLDOC documentation at http://www.htmldoc.org for details of the format of the header and footers. In addition, the genpdf script will perform variable substition for the %GENPDFADDON _BANNER%, %GENPDFADDON _TITLE%, and %GENPDFADDON _SUBTITLE% variables as it does for the title page. Finally, the PDFSTART and PDFSTOP HTML comments should be placed at the beginning and end of header/footer topic. An example header/footer page can be found at GenPDFExampleHeaderFooterTopic.

Frequently Asked Questions

How do I stop the table of contents from being generated?

For some topics, like User topics, it doesn't make any sense to have a table of contents generated so add 'pdftoclevels=0' as a URL parameter.

When I do a recursive PDF of WebHome it doesn't include all topics

That's because some topics distributed with Foswiki don't have a parent association. If you really want to include every topic in the web, you should reparent them all with WebHome as the parent.

Ocassionally no PDF document is generated

The default structure of book requires that headings be present in the topic. Try setting pdfstruct=webpage

Add-On Installation Instructions

Note: You do not need to install anything on the browser to use this add-on. The following instructions are for the administrator who installs the add-on on the server where Foswiki is running.

• Install htmldoc from http://www.htmldoc.org/ (optionally use the patch in the Addon's zip file for headers on every page)
• Download the ZIP file from the Add-on Home (see below)
• Unzip GenPDFAddOn.zip in your Foswiki installation directory. Content:

File:	Description:
bin/genpdf
data/System/GenPDFAddOn.txt	Add-on topic
data/System/GenPDFAddOnDemo.txt	Demonstration topic
data/System/GenPDFExampleHeaderFooterTopic.txt
data/System/GenPDFExampleTitleTopic.txt
htmldoc_force_header.patch
lib/Foswiki/Contrib/GenPDF.pm
lib/Foswiki/Contrib/GenPDFAddOn/Config.spec
templates/view.genpdf.tmpl

• Adjust the script ownership to match your webserver configuration (e.g. chown nobody genpdf) if needed.
• Make sure the script is executable (e.g chmod 755 genpdf).
• Adjust the perl path in the genpdf script to match your perl installation location.
• BEFORE Foswiki-4 Add the variable $htmldocCmd = "/path/to/htmldoc"; to your lib/Foswiki.cfg file so Foswiki can find the location of the htmldoc executable. Look for $fgrepCmd.
• Foswiki-4 and later Configure the $Foswiki::cfg{Extensions}{GenPDFAddOn}{htmldocCmd} = "/path/to/htmldoc"; using configure (in the Extensions section)
• Copy the preferences from above and paste them into SitePreferences, or the WebPreferences topic for a single web.
• Test if the installation was successful:
  • Try loading this page
  • If it doesn't work, check your webserver logs for any problems. The most common issue is probably an htmldoc installation problem.

Known Bugs

• Verbatim text runs off the page. This is a limitation of HTMLDOC. Preformatted text may run off the edge of the page and be truncated.
• HTMLDOC crashes with segmentation faults. Eg it fails to generate CompleteDocumentation. I managed to get it to work a few times, but it generally fails. The error returned is Conversion failed: 'Inappropriate ioctl for device' at /var/www/Foswiki/lib/Foswiki/Contrib/GenPDF.pm line XXX
• Some pages don't have a header. HTMLDOC breaks the page for every level 1 heading (Eg. <h1>) but it doesn't write a header for the new page, so topics with lots of level 1 headings and not much content don't seem to have any headers. Therefore I patched htmldoc-1.8.24 to force a header for every new page:

*** htmldoc-1.8.24/htmldoc/ps-pdf.cxx   Sat Oct 30 05:53:59 2004
--- htmldoc-1.8.24/htmldoc/ps-pdf_force_header.cxx      Tue Jun 13 02:12:28 2005
***************
*** 1465,1471 ****

      pspdf_prepare_heading(page, print_page, pages[page].header, top,
                            page_text, sizeof(page_text),
!                         page > chapter_starts[chapter] ||
                              OutputType != OUTPUT_BOOK);
      pspdf_prepare_heading(page, print_page, pages[page].footer, 0,
                            page_text, sizeof(page_text));
--- 1465,1472 ----

      pspdf_prepare_heading(page, print_page, pages[page].header, top,
                            page_text, sizeof(page_text),
! /*                      page > chapter_starts[chapter] || */
!                         1 || /* force heading onto chapter front page */
                              OutputType != OUTPUT_BOOK);
      pspdf_prepare_heading(page, print_page, pages[page].footer, 0,
                            page_text, sizeof(page_text));

Add-On Info

Add-on Author:	Foswiki:Main/BrianSpinar, Foswiki:Main/WadeTurland, Foswiki:Main/GeorgeClark
Change History:
28 Feb 2009	Added missing Config.spec file Item1161: GenPDFAddOn result in "Not Found" page
Feb 2009	Conversion to Foswiki. Better <a and <img tag handling. Rewrote attachment handling to use Func:: API Rewrote recursive mode to use %SEARCH
24 Dec 2008	Added FIRSTPAGE, DESTINATION, TITLEDOC, PAGELAYOUT & PAGEMODE. fixed tag rendering, again. Now accepts either quote. Incorporated body extraction patch; made it work for title pages. removed outdated comment from example title page. Limited testing; use previous version if that makes you nervous. -- Foswiki:Main/TimotheLitt
02 Jul 2008	added support for VIEW_TEMPLATE and COVER; fixed rendering of anchor and img tags; added pdfstruct parameter to print unstructured webpages as well; Foswiki:Main.MichaelDaum
25 Jun 2008	added template activation and Configure script spec file Foswiki:Main.SvenDowideit
25 Jun 2008	security and Foswiki 4.2 fixes Foswiki:Main.SvenDowideit
2 Nov 2007	Added new header and footer control (Bugs:Item4916) and fixed generation of wrong Foswiki page (Bugs:Item4915)
23 Oct 2007	Fixed Bugs:Item4452 & Bugs:Item4885, compatibility with Perl 5.6 and missing images with SSL certificates
31 Aug 2007	Fixed Bugs:Item4530, improper rendering of lists
13196	Removed nop tags before sending to htmldoc, fixed Bugs:Item3549
11673	Foswiki:Main/RickMach updated MIME type to pdf from x-pdf, fixed bug preventing disabling the TOC
9716	Foswiki:Main/CrawfordCurrie added content-disposition header to files, so they download using a sensible file name
9683	Foswiki:Main/CrawfordCurrie updated for Foswiki-4
Version 0.6 (28 Jun 2005)	Less aggressive regex for removing foswikiNewLink spans so it doesn't break when using the Foswiki:Extensions.SpacedWikiWordPlugin Added 'recursive' preference to include chapters for all descendents of the base topic Use File::Spec->tmpdir to specify the default directory for temporary files
Version 0.5 (16 Jun 2005)	Redirect to 'oops' URLs if permission denied or topic does not exist. Removed foswikiNewLink spans from title page so they render as normal text (without the blue ? mark). Fully qualify image/href URLs on the title page. Changed temp files to use OO style 'new File::Temp;' for better code portability.
Version 0.4 (13 Jun 2005)	Better security (now calls system($Foswiki::htmldocCmd, @htmldocArgs) ) Checks return code of htmldoc and returns an error on failure Validation of preferences Preferences changed to comply with Plugins standard Better HTML3.2 compatibility for htmldoc 1.8.24 (downgrades a few elements) Full integration of PDF META tags (optionally using 2 FORMFIELDs): ==%FORMFIELD{"TopicHeadine"}%== for PDF Subject field ==%FORMFIELD{"KeyWords"}%== for PDF Keywords field all other PDF fields use topic info More htmldoc options (margins, permissions, numbered TOC, logoimage, headfootfont) using preferences Removed %TOC% fields so it only uses HTMLDOC's TOC Title topic and header/footer topics are now fully rendered Fixed the heading shifting function Fully qualify links, making the document portable HTMLDOC output goes to a temp file instead of stdout Temp files now use 'GenPDFAddOn' prefix. (Eg. /tmp/GenPDFAddOn1wr3C48ibd.html)
Version 0.3 (12 Apr 2005)	Added full Foswiki rendering to title topic page Added Foswiki common variable expansion to header/footer topic page
Version 0.2 (26 Mar 2005)	Fixed bug with table of contents generation (i.e. it was always generated even if pdftoclevels was set to 0) Now allow multiple PDFSTART/PDFSTOP pairs within a single page to include/exclude multiple sections of the same page Added Brent Robert's fix to allow operation with latest version (1.8.24) of HTMLDOC
Version 0.1 (30 Jan 2005)	Initial version
CPAN Dependencies:	File::Temp (if for some reason you don't already have it installed )
Other Dependencies:	HTMLDOC (http://www.htmldoc.org)
Perl Version:	5.005 or above
License:	GPL
Add-on Home:	http://foswiki.org/Extensions/GenPDFAddOn
Feedback:	http://foswiki.org/Extensions/GenPDFAddOnDev
Appraisal:	http://foswiki.org/Extensions/GenPDFAddOnAppraisal

Related Topic: ContributedAddOns

-- TWiki:Main/WadeTurland - 28 Jun 2005
-- TWiki:Main/BrianSpinar - 12 Apr 2005 Form definition 'PackageForm' not found