Generate PDF Add-On

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' on the lower action bar with 'Generate PDF', eliminating the HTML printable view of the topic.
  • eg Set SKIN=genpdf,pattern (add ?skin=genpdf,pattern to the end of the URL to test)
• A page can also be published by substituting genpdf for view in the topic URL. (If using short URLs, insert /bin/genpdf/ prior to the Web name).
• To make it even easier for novice Foswiki users to use, you can add a link (like edit and attach) to view.tmpl to publish the current page (using the current topic as the document title). For example:

  <a href="%SCRIPTURLPATH%/genpdf%SCRIPTSUFFIX%/%WEB%/%TOPIC%?pdftitle=%TOPIC%">PDF</a>

• Another option is to create a global variable that inserts a PDF ICON in the document. The following variable is expanded in the upper-right corner of this page. You can click it to get a PDF of this page. If you set this in your SitePreferences topic, it can be used in any topic.

   * Set GENPDFLINK=<span style="margin:0 0 2em 5em; width:64px height:64px; text-align:center; float:right">
   [[%SCRIPTURL{"genpdf"}%/%WEB%/%TOPIC%?%QUERYSTRING%][<img src="%PUBURL%/System/GenPDFAddOn/pdf-64.gif">]]
   </span>

• You may also choose to replace the Printable (?skin=print) targets in your favourite skin with

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

GenPDFPlugin helper plugin

• Simulated: https://wiki.machs.org/bin/genpdf/System/GenPDFAddOn
• If Installed: https://wiki.machs.org/bin/genpdf/System/GenPDFAddOnPlugin

• Simulated: https://wiki.machs.org/bin/genpdf/System/WebHome
• If Installed: https://wiki.machs.org/bin/genpdf/System/WebHome

• Simulated: WebHome
• If Installed: WebHome

Configuring the Script

General Configuration

URL Variable	Foswiki Preference Variable	Default Value	Example	Explanation
pdfbanner	_BANNER		Foobar Documentation System	Used to override the banner of a title page.
pdftitle	_TITLE		Writing Foobars
pdfsubtitle	_SUBTITLE		A short guide to creating foobar documents
pdfheadertopic	_HEADERTOPIC		MyHeader	The name of a topic that defines headers and footers using <-- HEADER LEFT "foobar" --> syntax. See example
pdftitletopic	_TITLETOPIC		MyTitle	The name of a topic that defines the layout of the title page See example
pdftitledoc	_TITLEDOC			The name of an attachment if specified ,becomes the title page. Allows images - see htmldoc manual
skin	_SKIN	pattern	nat	Default skin to use for PDF generation
cover	_COVER	print	print.nat	Default cover to use for PDF generation
pdfcharset	_CHARSET	over-ride the Foswiki Site CharSet.
rev			rev=10	Generate a PDF from a prior topic revision. This disables pdfrecursive
pdfrecursive	_RECURSIVE		on	Include children of the base topic in the PDF
pdfformat	_FORMAT	pdf14	pdf12	HTMLDOC output format
pdftoclevels	_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	_PAGESIZE	a4	letter	The page size for PDF output
pdforientation	_ORIENTATION	portrait	landscape	The page orientation (e.g. landscape or portrait)
pdfwidth	_WIDTH	860	1060	The pixel width of the browser (used to scale images--images wider than this will be truncated)
pdfheadershift	_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). Can also be set to auto to cause headers to shift according to the depth of recursive rendering
pdfkeywords	_KEYWORDS	%FORMFIELD {"KeyWords"}%	'foo, bar, baz, zip'	Used for PDF Keywords META info to help search engines
pdfsubject	_SUBJECT	%FORMFIELD {"TopicHeadline"}%	'Foobar document creation'	Used for PDF Subject META info to help search engines
pdftoctitle	_TOCTITLE		Contents	See http://www.htmldoc.org/ Default is to use the htmldoc provided string "Table of Contents". Note that a current limitation is that strings containing embedded spaces are not passed correctly.
pdftocheader	_TOCHEADER	...	l..	See http://www.htmldoc.org/
pdftocfooter	_TOCFOOTER	..i	.i.	See http://www.htmldoc.org/
pdfbodyfont	_BODYFONT			Specify font for body of document (Arial, Courier, Helvetica, Monospace, Sans, Serif, or Times
pdfheadingfont	_HEADINGFONT			Specify font for headings of document (Arial, Courier, Helvetica, Monospace, Sans, Serif, or Times
pdftextfont	_TEXTFONT			Specify font for all text in document (Arial, Courier, Helvetica, Monospace, Sans, Serif, or Times
pdfheader	_HEADER		.1.	Specify content of header, see http://www.htmldoc.org
pdffooter	_FOOTER		.1.	Specify content of footer, see http://www.htmldoc.org
pdfheadfootfont	_HEADFOOTFONT		Helvetica-Bold	Font specification for headers and footers.
pdfheadfootsize	_HEADFOOTSIZE		12	Sets the size of the header and footer text in points (1 point = 1/72nd inch)
pdfbodyimage	_BODYIMAGE			The image that will appear tiled in the background of every page
pdflogoimage	_LOGOIMAGE			The logo that will appear in a header or footer if you specify 'l' in the string (see http://www.htmldoc.org)
pdfnumberedtoc	_NUMBEREDTOC		True	Option flag for getting numbered headings and Table of Contents. Set it to anything for true.
pdfduplex	_DUPLEX		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	_PERMISSIONS		print,no-copy	PDF Security permissions to disable print/copy etc. By default the PDF is not protected.
pdfmargins	_MARGINS		top:0.5in, bottom:2.5cm, left:12pt, right:15mm	Specify the page margins (white space to edge of page)
pdfbodycolor	_BODYCOLOR		#CCff99	Specify the background colour of all pages
pdfstruct	_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	_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	_DEBUG	0	1	Include debug messages and don't clean up temporary files after execution
pdffirstpage	_FIRSTPAGE	toc		First page viewer will open: toc table of contents; p1 first page; c1 first chapter.
pdfdestination	_DESTINATION	view		Output to browser window or save-as prompt
pdfpagelayout	_PAGELAYOUT	single		View's initial presentation layout: single, one, twoleft, tworight
pdfpagemode	_PAGEMODE	outline		Viewer's initial presentation mode: outline, document, fullscreen
pdfcompress	_COMPRESS		9	Set compression level of the document. 1=minimum, 9=maximum, none to disable compression
pdfjpegquality	_JPEGQUALITY		80	Set JPEG image quality. Lower quality is higher compression. Set to none to disable JPEG image compression

• 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_CHARSET =
  • #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_TOCTITLE =
  • #Set GENPDFADDON_TOCHEADER =
  • #Set GENPDFADDON_TOCFOOTER =
  • #Set GENPDFADDON_BODYFONT =
  • #Set GENPDFADDON_HEADINGFONT =
  • #Set GENPDFADDON_TEXTFONT =
  • #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_TEMPLATE =
  • #Set GENPDFADDON_COPYRIGHT =
  • #Set GENPDFADDON_DEBUG =
  • #Set GENPDFADDON_FIRSTPAGE =
  • #Set GENPDFADDON_DESTINATION =
  • #Set GENPDFADDON_PAGELAYOUT =
  • #Set GENPDFADDON_PAGEMODE =
  • #Set GENPDFADDON_COMPRESS =
  • #Set GENPDFADDON_JPEGQUALITY =

Limiting the PDF Generation Region

• 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.

Creating and Configuring a Title Page

Creating and Configuring Headers and Footers

Recursive rendering of topics

• The default behavior is to render each topic as a separate chapter. A level 1 heading will be added as required to each topic.
• Child topics are sorted into alphabetical order by topic name
• If the pdfheadershift option is set to auto, then the first header in each topic will be set to the absolute depth of the child topic in the tree. In this case the PDF will consist of only a single chapter.
• Any topic can be promoted a level in the hierarchy by including the HTML comment <!-- TOC PROMOTE --> anywhere in the topic.
  • Promoted Child topics will appear after all other children have been expanded.
  • The actual parent of the topic is not changed, so topics cannot be promoted more than one level without breaking the topic sort order.
• Child topics are not found across web boundarys.

ParentTopic
   - FirstChild
      - GrandChildOne
      - GrandChildTwo
   - SecondChild
      - GrandChildThree
   - ThirdChild

1 ParentTopic
2 FirstChild
3 GrandChildOne
4 GrandChildTwo
5 SecondChild
6 GrandChildThree
7 ThirdChild

1 ParentTopic
 1.1 FirstChild
  1.1.1 GrandChildOne
  1.1.2 GrandChildTwo
 1.2 SecondChild
  1.2.1 GrandChildThree
 1.3 ThirdChild

1 ParentTopic
 1.1 FirstChild
  1.1.1 GrandChildOne
  1.1.2 GrandChildTwo
 1.2 ThirdChild 
2 SecondChild
 2.1 GrandChildThree

Generating PDF from a older revision of a topic.

Limitations

• Specifying a topic revision will disable the recursive option.
• The revision is only applied to the primary topic. All other related topics - title pages, includes, attachments, etc. use the current revision.
• Any in-topic settings GENPDFADDON_* will be taken from the curent version and not from the requested topic revision.

PDF Logos

• 32x32 Images
  pdf-32.gif
  pdf-32.png

• 64x64 Images
  pdf-64.gif
  pdf-64.png

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

Before you upgrade!

• This version moves the GenPDFAddOn examples and demo topics from the %System web to the Sandbox web. Old versions of these topics can be removed %from the System web after the upgrade.
• The hard-coded pdftoclevel=0 in the view.genpdf.tmpl file has been removed. An alternative approach is to set GENPDFADDON_TOCLEVELS=0 in SitePreferences
• This version ships with a GenPDFPlugin. This is a helper plugin which will expand the %GENPDF% tag, and does not need to be enabled. See GenPDFPlugin for more information
• This version renames lib/Foswiki/Contrib/GenPDF.pm to lib/Foswiki/Contrib/GenPDFAddOn.pm A shim version of GenPDF.pm is shipped so that existing configurations will still work without requiring any configuration changes to =lib/LocalSite.cfg

Standard installation

• Install htmldoc from http://www.htmldoc.org/ (optionally use the patch in the Addon's zip file for headers on every page)
• Access the bin/configure script - Extensions tab, click "Find Extensions", locate GenPDFAddOn in the table and click "Install"
• In the bin/configure script, visit the GenPDFAddOn settings and optionally set the path to the htmldoc command. If this is not set, the plugin will look for htmldoc in the default path.
  • You must go through a save cycle in bin/configure in order to set the required hidden Switchboard entry even if you have not changed any settings!
• Windows Users: Edit the bin/genpdf script and update the "shebang" #!/bin/perl to match your system perl location
  
  • Example: #!C:\strawberry\perl\bin\perl.exe
• Important Security considerations
  • The genpdf script should be added to the AuthScripts list in bin/configure
  • if you use Apache user authentication, be sure to also add genpdf to the list of restricted scripts in the apache configuration.
• Copy any desired 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 you get a 404 - not found, make sure that a switchboard entry exists in LocalSite.cfg.
  • If it doesn't work, check your webserver logs for any problems. The most common issue is probably an htmldoc installation problem.
  • Another test topic is found in Sandbox/GenPDFAddOnDemo

Alternative installation

• Download the tgz or zip file and the GenPDFAddOn_installer file from the Add-on Home (see below)
• Run the installer ( perl GenPDFAddOn _installer ) or unzip GenPDFAddOn.zip in your Foswiki installation directory
• 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.
• Configure the $Foswiki::cfg{Extensions}{GenPDFAddOn}{htmldocCmd} = "/path/to/htmldoc"; using configure (in the Extensions section)
  • You must visit and save the Foswiki configuration at least once after installation to set a hidden variable in the LocalSite.cfg file
  • See the Configuration file settings below.

Configuration file settings

$Foswiki::cfg{Extensions}{GenPDFPlugin}{htmldocCmd} = '/usr/bin/htmldoc';
$Foswiki::cfg{SwitchBoard}{genpdf} = {
          'function' => 'viewPDF',
          'context' => {
                         'view' => 1
                         'static' => 1
                       },
          'package' => 'Foswiki::Contrib::GenPDF'
        };

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