Extension:PdfBook
From MediaWiki.org
 Release status: stable |
|
|---|---|
| Implementation | Data extraction |
| Description | Composes a book from articles in a category and exports as a PDF file |
| Author(s) | nadTalk |
| Last Version | 1.0.1 (2008-10-26) |
| License | GPL |
| Download | Download snapshot |
|
check usage (experimental) |
|
Contents |
[edit] Overview
Categories are a good way of organizing many articles which together comprise a kind of book. The sort-key's in the article's categorization statements can be used to ensure that they're ordered properly. This extension allows such categories to be composed into downloadable PDF files with a table of contents and each article forming the start of a new chapter.
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: Since version 1.0.1, PdfBook can also export single articles by using format=single in the URL
[edit] Installation
First Htmldoc needs to be installed (on Debian based systems such as Ubuntu or Mepis use: apt-get install htmldoc). Windows Binary can be found here. Download the latest snapshot, save into your extensions directory and include into your LocalSettings.php:
require_once( "$IP/extensions/PdfBook/PdfBook.php" );
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.
[edit] Usage
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.
[edit] Raw HTML output
You can download the file as a single HTML document by setting format=html in the query-string.
[edit] Single page exports
You can export a single article as a one-page PDF by setting format=single in the query-string.
[edit] Page Breaks
You can add page breaks into your book by adding <!-- PAGE BREAK --> into the relevant places in the content articles.
[edit] Configuration
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 |
|---|---|---|
| $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 |
[edit] Bugs and Todo
- 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.
[edit] Change log
- Version 0.0.12 (2008-06-22): Syntax error fixed
- Version 0.0.11 (2008-05-30): Add quotes to $cat and use select() wrapper for query
- Version 0.0.10 (2008-04-16): Function onUnknownAction() should return true if it's not our action
- Version 0.0.9 (2007-11-01): Remove TOC of individual articles since main book has its own TOC
- Version 0.0.8 (2007-10-29): Don't absoluterise if already absolute
- Version 0.0.7 (2007-09-27): Allow download as HTML before conversion to PDF by setting format=html
- Version 0.0.6 (2007-09-26): Fixed images
- Version 0.0.5 (2007-09-25): Extract titles from bullet lists of article links if not a category page
[edit] See also
- Extension:Collection - allows to 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
