Extension:PdfHandler

MediaWiki extensions manual

PdfHandler Release status: stable
Implementation	Media
Description	Allows to handle PDF files like multipage DJVU
Author(s)	Martin Seidel (xarax)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
Database changes	No
Parameters $wgPdfHandlerJpegQuality $wgPdfOutputExtension $wgPdfInfo $wgPdfProcessor $wgPdftoText $wgPdfPostProcessor $wgPdfHandlerDpi
Hooks used LocalFilePurgeThumbnails
Licence	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Browse repository (Phabricator · GitHub) Gerrit code review Git commit log Download source tarball
Example	commons.wikimedia.org sandbox.semantic-mediawiki.org
Translate the PdfHandler extension if it is available at translatewiki.net
Vagrant role	pdfhandler
Issues	Open tasks · Report a bug

The PdfHandler extension shows uploaded PDF files in a multipage preview layout.

Together with the Proofread Page extension, PDF files can be displayed side-by-side with text. This allows users to transcribe books and other documents.

Usage

• A user can display PDF files as an image, showing a single page at a time, like so: [[File:myPdfFile.pdf|page=1|600px]]. The page and size parameters are optional; the default page is page #1. Instead of a size-parameter, you can also use the thumb-parameter, with or without captions: [[File:myPdfFile.pdf|page=1|thumb|My PDF]].
• Because PdfHandler extends ImageHandler, you can use all the arguments that you would for an Image -- for example: thumb, right/left, caption, border, link, etc.

If you would like to present a 2-page pdf, for example, do the following: [[File:myPdfFile.pdf|page=1]] [[File:myPdfFile.pdf|page=2]]

• The main usage of the PdfHandler extension is without user interaction. If you upload a new pdf file, the metadata will be stored in the database, and then this file can be shown in a multipage preview layout like the djvu handler does. Without this extension, pdfs will not display properly when uploaded.
• Additionally, this extension allows Extension:ProofreadPage to handle pdfs in side-by-side view for transcribing/proofreading, as is done on Wikisource

Pre-requisites

This extension requires the following packages to be installed first:

Package	Description	Link
ghostscript	Renders the page images. It provides the command gs.	www.ghostscript.com
imagemagick	Does dynamic resizing and thumbnailing of images. It provides the command convert.	www.imagemagick.org
xpdf-utils poppler-utils	Extracts metadata from PDF files. If you see "0 × 0 pixel" on the file description of a PDF, you lack this package. It provides the command pdfinfo.	www.xpdfreader.com On Ubuntu and Debian, the "poppler-utils" package can be used instead of "xpdf-utils".

Type the following in your shell to see if you have the above installed first (it should list 4 rows):

which gs convert pdfinfo pdftotext

If something is missing, install the related packages. Example in Debian and Ubuntu:

sudo apt install ghostscript imagemagick xpdf-utils

If you are unable to install these packages, kindly contact your server administrator for assistance in your environment.

Installation

This extension comes with MediaWiki 1.21 and later, so you do not need to download it. The remaining configuration instructions must still be followed.

• Make sure that the required software is installed before you continue!
• Download and move the extracted PdfHandler folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:

  cd extensions/
  git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PdfHandler
  

• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'PdfHandler' );
  

• Configure as required. (see also the examples provided)
• Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

You can (or, depending on the operating system of the server, will have to) set some variables in the "LocalSettings.php" file:

Name	Default	Description
$wgPdfProcessor	"gs"	path to your ghostscript implementation
$wgPdfPostProcessor	"convert"	path to your imagemagick convert
$wgPdfInfo	"pdfinfo"	path to your pdfinfo
$wgPdftoText	"pdftotext"	path to your pdftotext
$wgPdfOutputExtension	"jpg"	preferred output format
$wgPdfHandlerDpi	"150"	resolution in dpi The extension extracts a bitmap image for each page of the PDF, using this resolution (dpi = dots per inch). For example, a PDF page with the European size A4 is 210 mm wide, corresponding to 595 points (at 72 dpi). This yields an image 1240 pixels wide (at 150 dpi). If instead this parameter is set to 300 dpi, the width will be 2480 pixels.
$wgPdfHandlerJpegQuality	"95" (introduced in 1.24)	Quality level, which the post processor should use.

Variables below are not specific to this extension

• Enable PDF uploads, if you haven't already: $wgFileExtensions [] = 'pdf';
• Enable ImageMagick, if you haven't already: $wgUseImageMagick = true;
• $wgMaxShellMemory - memory limit for gs, convert and pdfinfo. The default value might be too low.

Ubuntu

This is identical to the default settings for this extension.

$wgPdfProcessor = 'gs';
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = 'convert'; // if not defined via ImageMagick
$wgPdfInfo = 'pdfinfo';
$wgPdftoText = 'pdftotext';

Debian

$wgPdfProcessor = '/usr/bin/gs';
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = '/usr/bin/convert';  // if not defined via ImageMagick
$wgPdfInfo = '/usr/bin/pdfinfo';
$wgPdftoText = '/usr/bin/pdftotext';

Windows

$wgPdfProcessor = 'C:\Program Files\gs\gs8.60\bin\gswin32.exe';
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = 'C:\Program Files\ImageMagick-6.6.2-Q16\convert.exe'; // if not defined via ImageMagick
$wgPdfInfo = 'C:\Program Files\xpdf-3.02pl1-win32\pdfinfo.exe';
$wgPdftoText = 'C:\Program Files\xpdf-3.02pl1-win32\pdftotext.exe';

macOS

$wgPdfProcessor = '/usr/local/bin/gs';
$wgPdfPostProcessor = $wgImageMagickConvertCommand; // if defined via ImageMagick
// $wgPdfPostProcessor = '/usr/local/bin/convert'; // if not defined via ImageMagick
$wgPdfInfo = '/usr/local/bin/pdfinfo';
$wgPdftoText = '/usr/local/bin/pdftotext';

Troubleshooting

• If PDF files do not display after upload, make sure that MediaWiki can execute the pdfinfo command and that configuration parameter $wgPdfInfo is set properly. Also check your error log, and make sure that your host hasn't disabled running external commands.
• If PDF files do not show properly after installation (for example, showing "0 × 0 pixels") you may need to use the Maintenance scripts refreshImageMetadata.php and/or rebuildImages.php. For example:

  $ php ./maintenance/run.php refreshImageMetadata --mime application/pdf --force
  

  Also try to purge the page of the file. See Manual:Purge .

• If PDF files are rendered randomly check if the "C.UTF-8" locale is available on your server by running locale -a.

See also

• http://wiki.4intra.net/PdfHandler — a fork with much faster thumbnail generation by using pdftocairo instead of ghostscript+imagemagick
• Extension:Proofread Page — may be used in conjunction with PdfHandler
• How to use DjVu with MediaWiki
• Extension PDFEmbed