[[PageOutline(2-5,Contents,pullout)]]

= !PdfImages as PNG in Wiki

== Description

This plugin inserts vector graphics like PDFs or SVGs as PNG-images into a Trac wiki page or ticket.

It requires `convert` from [http://www.imagemagick.org ImageMagick]. However, `convert` may fail on specific files. Additionally, Ghostscript is required for `convert` on Windows, which is available [http://pages.cs.wisc.edu/~ghost/doc/GPL/gpl902.htm here].

The handling and the parameters are inspired by LaTeX includegraphics and the Trac !ImageMacro. 

Examples:
{{{
[[PdfImg(Book.pdf,width=400,page=100,caption="Page 100 from Book Example")]]
[[PdfImg(source:testpro/drawing.svg@10,width=600,caption="SVG-image from repository in version 10")]]
[[PdfImg(ticket:1:file.pdf)]]
}}}

=== Acknowledgement

'''Note''': PDF conversion with !ImageMagick-`convert`:
 1. may fail on specific PDFs. This is not a problem of the plugin, but of `convert`. In this case you will get an error like "{{{ Can't display foo.pdf, ImageMagick->convert failed with errorcode=... , command=convert ... }}}"
 2. if not restricted to certain pages, it can take very long; example: Converting a PDF file of 400 pages by simply {{{ [[PdfImg(test.pdf)]] }}} took several minutes! See #9874, #9875.

=== Requirements

 * Install `convert` from the [http://www.imagemagick.org ImageMagick]-suite.
 * Tested on Linux.

Tested on this configurations:
|| '''Operating System''' || '''Trac'''          || '''Imagemagick''' ||
|| Ubuntu 11.04         || 0.11.7-4 (deb)        || 7:6.6.2.6-1ubuntu ||
|| Ubuntu 10.04.4 LTS   || 0.12.2 (easy_install) || 7:6.5.7.8-1ubuntu ||
|| Win64 Server 2003 R2 || 0.12.2 (Bitnami)      || [http://www.imagemagick.org/script/binary-releases.php?ImageMagick=r33s1i1qna69puo410jup92sp2#windows ImageMagick-6.7.5-6-Q16-windows-x64-dll.exe][[BR]][http://pages.cs.wisc.edu/~ghost/doc/GPL/gpl902.htm Ghostscript gs902w64.exe] || 

=== Parameters
    
Possible Trac links for resource:
The Location of the file can be an attachment (wikipage, ticket, svn) or a local file (keyword "file:").
||= '''Trac link (resource)''' =||= '''Alternatives''' =||= '''Comment''' =||
|| wiki        ||  !JustPageName || Attachment in wikipage ||
|| ticket      ||  !#1           ||                        ||
|| source      ||  browser,repos ||                        ||
|| file        ||                || need configuration `file.prepath`   ||
      
Parameters:
||= '''Parameter''' =||= '''Value'''     =||= '''Default''' =||                   || 
|| `pdffile`   || resource of PDF-file    ||           || required                ||
|| page        || Page to display         || 1         || starting with '''1'''   ||  
|| width       || width in pixel          || 600       || must be absolute value  ||  
|| caption     || Caption under Image     || ''none''  ||                         ||  
|| label       || anchor to link to       ||           ||                         ||
|| || || || ||
|| cache       || build once or each time || True      || time consumption or changing vectorgraphics ||
|| align       || left|right              || nothing   ||                         ||

== Bugs/Feature Requests

Existing bugs and feature requests for PdfImagePlugin are 
[report:9?COMPONENT=PdfImagePlugin here].

If you have any issues, create a 
[/newticket?component=PdfImagePlugin&owner=ursaw new ticket].

[[TicketQuery(component=PdfImagePlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:pdfimageplugin here].

== Source

You can check out PdfImagePlugin from [/svn/pdfimageplugin here] using Subversion, or [source:pdfimageplugin browse the source] with Trac.

== Example

{{{
[[PdfImg(Book.pdf,width=400,page=100,caption="Page 100 from Book Example")]]
[[PdfImg(sketch.svg,cache=False)]] 
[[PdfImg(OtherPage:foo.pdf)]]
[[PdfImg(file:relpath/to/foo.pdf)]]
}}}

which is then displayed as:

[[Image(PdfImg_screenshot.png)]]

== Configuration

No configuration is needed except to use the Resource 'file:' the following configuration must be set: 

Suppose your server is ''http://example.com'' and the webserver config mapped your local directory `/absolute/entry/directory` to the public directory `entrydir`, then your configuration for the ''file:''-resource looks like:

{{{#!ini
[pdfimg]
file.prepath = /absolute/entry/directory
file.preurl = http://example.com/entrydir
}}}

== Recent Changes

[[ChangeLog(pdfimageplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:ursaw] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''