Extension:PdfBook

From MediaWiki.org
(Redirected from Extension:Pdf Book)
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
PdfBook

Release status: stable

Implementation Data extraction
Description Composes a book from articles in a category and exports as a PDF file
Author(s) Aran Dunkley (nadtalk)
Latest version 1.2.3 (2013-09-19)
Database changes No
License GPL v2+
Download GitHub

CHANGELOG
Parameters

$wgPdfBookTab,
$wgPdfBookLeftMargin,
$wgPdfBookRightMargin,
$wgPdfBookTopMargin,
$wgPdfBookBottomMargin,
$wgPdfBookFont,
$wgPdfBookFontSize,
$wgPdfBookLinkColour,
$wgPdfBookTocLevels,
$wgPdfBookExclude

Hooks used
UnknownAction

SkinTemplateTabs
SkinTemplateNavigation

Translate the PdfBook extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

Issues:

Open tasks · Report a bug
The Wikimedia Foundation is working on a newer PDF rendering functionality that will be supported out of the box.

The PdfBook extension composes a book from articles in a category and exports as a PDF file.

Overview[edit | edit source]

Categories are a good way of organizing many articles which together comprise a kind of book. The sort-keys in the articles' categorization statements can be used to ensure that they are ordered properly. This extension allows such categories to be compiled into downloadable PDF files with a table of contents, each article forming the start of a new chapter.

Note Note: In version 0.0.5, a new feature has been added which allows books to be generated from non-category pages as well. If the article to be downloaded as a book is not a category, then the extension will extract the titles from article links in a bullet list. The list may be explicitly defined, or may be the result of a query. For an example of this functionality, see Creating a PDF book from a DPL query

Note Note: Since version 1.0.1, PdfBook can also export single articles by using format=single in the URL

Installation[edit | edit source]

Pre-requisite
  • First Htmldoc needs to be installed.
  • On Debian based systems such as Ubuntu or Mepis use: apt-get install htmldoc.
  • Compile or install HTMLDOC on Windows and add HTMLDOC to the PATH.
  • On Mac OS X: Downloading from source, using the common "./configure; make; sudo make install" procedure" works if you have those developer tools installed.
  1. Download the files from SVN or download a snapshot (select your version of MediaWiki)
  2. Create a directory PdfBook in your $IP/extensions directory
  3. Extract the files to this $IP/extensions/PdfBook directory
  4. Add to the end of LocalSettings.php:
    require_once("$IP/extensions/PdfBook/PdfBook.php");
  5. Installation can now be verified through Special:Version on your wiki

Note Note: I've noticed that MediaWiki 1.11+ requires more memory to create large books. If your book is around a hundred articles you'll need to give PHP 64MB.

Usage[edit | edit source]

The PDF creation is initialised by the pdfbook action, so a category can be downloaded as a PDF book directly from a link such as:

http://www.foo.bar/wiki/index.php?title=Category:foo&action=pdfbook

A more generic way of creating the link is to use the "fullurl" parser function and the FULLPAGENAMEE built in variable as in the following example.

[{{fullurl:{{FULLPAGENAMEE}}|action=pdfbook}} download this selection of articles as a PDF book]

This link can then be added to a template which can be transcluded into any category or article suitable for downloading as a book. For an example of such a template, see OrganicDesign:Category:I am that, which uses OrganicDesign:Template:Book to display the message and download link. In order to include this parser function link automatically to every category page, add it to the Mediawiki:Categoryarticlecount page.

Raw HTML output[edit | edit source]

You can download the file as a single HTML document by setting format=html in the query-string. Example:

http://www.foo.bar/wiki/index.php?title=Main_Page&action=pdfbook&format=html

Single page exports[edit | edit source]

You can export a single article as a one-page PDF by setting format=single in the query-string. Example:

http://www.foo.bar/wiki/index.php?title=Main_Page&action=pdfbook&format=single

Page Breaks[edit | edit source]

You can add page breaks into your book by adding <!-- PAGE BREAK --> into the relevant places in the content articles.

While using action=pdfbook&format=html to create an printable HTML from an category it seems not to work Use eg <h2 style="page-break-after: always;">End of the document '''{{FULLPAGENAME}}''' </h2> to create the page-break

Configuration[edit | edit source]

Here are some global variables which affect the operation of the extension. These should be set in your LocalSettings file after the include of the PdfBook.php script. These configuration options can be overridden by the parser function so that they can be set specifically for each book.

Variable Default value Meaning
$wgPdfBookTab false Whether or not an action tab is wanted for printing to PDF
$wgPdfBookLeftMargin 1cm Left page margin
$wgPdfBookRightMargin 1cm Right page margin
$wgPdfBookTopMargin 1cm Top page margin
$wgPdfBookBottomMargin 1cm Bottom page margin
$wgPdfBookFont Arial Default font to use if unspecified in content
$wgPdfBookFontSize 8 Point size of default font
$wgPdfBookLinkColour 217A28 Colour to use when rendering hyperlinks in text
$wgPdfBookTocLevels 2 Number of outline levels to use when building the table of contents
$wgPdfBookExclude empty List of article titles which should not be included in the book

Bugs and Todo[edit | edit source]

  • Multibyte characters not working
  • Tables are "hardwired" to a standard format currently
  • Dynamic per-book parameters not done yet
  • Interference with Extension:ASHighlight: Export halts on first encountered <source> tag. Use Extension:SyntaxHighlight GeSHi instead.
  • If pdfbook is generated from an article containing article links in a bullet list, all articles in the pdf have the title of the first article in the list, not their own.
    • Solution: change the line 122 of PdfBook.php to this: "$wgOut->setHTMLTitle( $ttext, true ); # use this so DISPLAYTITLE magic works"

See also[edit | edit source]

  • Extension:Collection - allows to build collections from a number of pages. Collections can be edited, persisted and retrieved as PDF
  • Extension:Pdf Export - use this extension for exporting single articles as PDF's