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

= Make Trac wiki pages printable

== Description

This plugin allows you to export to PDF (book or article format) or printable HTML format (page contents without Trac headers/footers) allowing easy printing. PDF export is based on [https://wkhtmltopdf.org/ wkhtmltopdf].

Older versions up to V3.0.0 used [http://www.xhtml2pdf.com/ xhtml2pdf] for generating PDF files. While having the advantage of being a pure Python solution it was abandoned because the output quality of [https://wkhtmltopdf.org/ wkhtmltopdf] is way better. For these unsupported older releases see [wiki:TracWikiPrintPlugin/WikiPrintXhtml2pdf WikiPrintXhtml2pdf].

{{{#!box width=720px
==== Example of an exported wiki page
[[Image(wiki:TracWikiPrintPlugin:wp_pdfpage_example.png, width=700px, border=2)]]
}}}

Key features:

* Administration page for default settings.
* Customizable footers for PDF.
* Customizable front page for PDF book format.
* Automatic creation of Table of Contents for PDF books.
* The style of the resulting PDF or HTML can be fully customized using CSS.
* Different page sizes.
* PDF "print dialog" for altering settings prior to PDF file creation.
* [#PdfBookmakro Makro] to specify contents and format of PDF Books with export feature.

The plugin is seamlessly integrated in the Trac user interface by adding items to the `Download in other formats` section of each wiki page.


See also
* TracWikiToPdfPlugin
* [wiki:TracWikiPrintPlugin/WikiPrintXhtml2pdf WikiPrintXhtml2pdf]

=== Supported Trac releases

Trac 1.4 and 1.6 are fully supported.

For older releases use TracWikiPrintPlugin V3.x.x or older. See [wiki:TracWikiPrintPlugin/WikiPrintXhtml2pdf WikiPrintXhtml2pdf] for more information.

== License

Releases up to {{{V3.x.x}}} were licensed as GPL.

With {{{V4.0.0}}} the plugin was rewritten from scratch and is now BSD licensed.

== Bugs/Feature Requests

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

If you have any issues, create a [/newticket?component=TracWikiPrintPlugin new ticket].

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

== Download

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

== Source

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

The plugin is also available on [pypi:TracWikiPrint PyPi].


== Installation

The plugin depends on [https://pypi.org/project/pdfkit/ pdfkit].
When installing with {{{pip}}} the library [https://pypi.org/project/pdfkit/ pdfkit] is automatically fetched. It is also possible to install the library as an `egg` using Tracs {{{plugin}}} admin page.

To install the plugin from trunk:

{{{#!sh
$ pip install svn+https://trac-hacks.org/svn/tracwikiprintplugin/trunk
}}}

To install the older `V3.0.0` release:

{{{#!sh
$ pip install svn+https://trac-hacks.org/svn/tracwikiprintplugin/tags/V3.0.0
}}}


Install [https://wkhtmltopdf.org/ wkhtmltopdf]. 

**Note:** `wkhtmltopdf` must be in your path or more precisely in the path used by Trac.

Enable the plugin using Tracs plugin administration page or by adding `tracpdf.* = enabled` in the ''components'' section of your `trac.ini` file:

{{{#!ini
[components]
...
tracpdf.* = enabled
}}}


== Configuration

Configuration can be done using the new administration page `Page Parameters` in section `Wikiprint`.

The settings can also be specified in `trac.ini`:

{{{#!ini
[wikiprint]
# Name of a wiki page used as the cover for a PDF book
coverpage = CoverPageInWiki

# One of the predfined footers to be added to a PDF. Leave empty for
# no footer.
#
# Available footers:
# 1: [page] / [topage]
# 2: {pagename}  -  [page] / [topage]
footertext = [page] / [topage]

# One of the predefined page sizes: A3, A4, A5, B4, B5, B6, Folio, Legal, Letter
pagesize = A4

# Name of a wiki page containing CSS style information.
# A style page must be located below WikiPrint/Styles/
# If left empty Tracs default wiki styles are used.
stylepage = WikiPrint/Styles/StylePage

# Title to be used in the PDF properties. If left empty
# the wiki page name will be used
title = 

# Whether to include a table of content in a PDF book
toc = enabled|disabled
}}}


== Permissions

Wikiprint defines a new permission:

 * `WIKIPRINT_ADMIN`: Allow users to access the `Page Parameters` admin page, and configure wikiprint default settings.

To actually view a wiki page and export it to PDF the user must have `WIKI_VIEW` permission.

== Usage

After the plugin is enabled, a new administration panel will be available under the `Wikiprint` section, and 4 new download formats will be available in the `Download in other formats` section at the end of each wiki page:

* Printable HTML
* PDF Page
* PDF Page (custom settings)
* PDF Book

A new [#PdfBookmakro makro] `PdfBook` can be used to create PDF books from any number of wiki pages.

=== Administration page

The default configuration for page exports may be provided using the `Wikiprint` administration page. These settings apply when not overriden by the user while exporting a PDF. While most settings are related to PDF files the style page specified here also applies when generating the `Printable HTML` page.

{{{#!box width=720px
==== Example of a PDF book
[[Image(wiki:TracWikiPrintPlugin:wp_admin_parameters.png, width=700px, border=2)]]
}}}


=== Printable HTML

The wiki page is stripped from Tracs footer, header and navigation. The resulting page only contains the wiki content.

Styling of the page is according to the style page selected using the administration panel.


=== PDF Page

`PDF Page` creates a PDF file out of the wiki page, with no cover page. Styles will be used from the style page defined in the global configuration set with the administration panel.

Table of contents macros in the wiki page like `[[PageOutline()]]` or others are not stripped from the page.

=== PDF Page (custom settings)

The wiki page is exported as a PDF file. This is like normal `PDF Page` export but it is possible to override the global configuration while generating the PDF file. A settings page similar to a "print dialog" is presented to the user before the actual export happens.

{{{#!box width=720px
==== Setting parameters for PDF page export
[[Image(wiki:TracWikiPrintPlugin:wp_pdfpage_settings.png, width=700px, border=2)]]
}}}



=== PDF Book

This will create a book-like PDF document. While exporting the user is presented with a settings page to specify a cover page and whether a table of contents should be added. Styling may be changed by selecting one of the available style pages. The cover page used for the book may be any wiki page.

Common table of contents macros in the wiki page like `[[PageOutline()]]` or `[[TracGuideToc()]]` are removed from each wiki page.

Each book starts with the cover page (if any) directly followed by the table of contents (if enabled).

{{{#!box width=720px
==== Example of a PDF book
[[Image(wiki:TracWikiPrintPlugin:wp_pdfbook_example.png, width=700px, border=2)]]
}}}


=== PdfBook makro

Using the makro it is possible to define PDF books with any number of wiki pages a cover page and table of contents. The configuration specified in the makro may always be overriden by the user while creating the book. This way one may for example change the predefined cover page or omit the table of contents. Note that you can't add or remove pages while creating the book.

The configuration from the makro is rendered to the user and a button added to create the PDF book. Note that only one PdfBook makro on a wiki page is supported.

The makro must be specified in WikiProcessors syntax:

{{{
{{{#!PdfBook
...
}}}
}}}

The contents must be formatted like an INI file. The following sections are defined:

* `[parameters]`: specify cover page and table of contents
* `[pages]`: list of wiki pages to add to the book.

{{{
{{{#!PdfBook
[parameters]
# Name of a wiki page to be used as the cover page
cover = CoverPage
# Set to 1 for a table of contents, else set to 0
toc = 1

[pages]
# Names of wiki pages to be added to the PDF book.
WikiStart
WikiFormatting
}}}
}}}

{{{#!box width=720px
==== Example of PdfBook makro
[[Image(wiki:TracWikiPrintPlugin:wp_pdfbook_makro.png, width=700px, border=2)]]
}}}

=== Custom styling

It is possible to use styles different to Tracs default CSS. A wiki page must be created below {{{WikiPrint/Styles/}}} containing the styles to use.

For example
{{{
WikiPrint/Styles/StylePage
}}}

The page will automatically be available for selection when creating PDF files and on the administration page.


== Recent Changes

[[ChangeLog(tracwikiprintplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:Cinc-th] [[BR]] 
'''Maintainer:''' [[Maintainer]] [[BR]] 
'''Contributors:'''