|Version 38 (modified by 4 years ago) (diff),|
- Usage instructions
- Bugs/Feature Requests
- Recent Changes
WikiPrint Trac Plugin
Make wiki pages easily printable, exporting to PDF (book or article format) or printable HTML format (page contents without trac headers/footers). PDF export is based on pure python libraries (such as xhtml2pdf and PISA), instead of depending on an external applications.
- Fully customizable header/footers for PDF
- Syntax highlighting in exported format, using pygments
- Customizable front page for PDF book format
- Automatic creation of Table of Contents if [[PageOutline]] or [[TOC]] Macro is used
The style of the resulting PDF or HTML can be fully customized using CSS files.
- 2011-09-26: Version 1.9.2. New option omit_macros to specify a list of macros to be removed on PDF.
- 2011-09-23: Version 1.9.1. Included omit_links and rebase_links options in .ini section.
- 2011-09-23: Version 1.9. Added link_format, omit_links and rebase_links options.
- 2010-05-05: Version 1.8.3. Some fixes, see Recent Changes below.
- 2010-02-22: Version 1.8. Some fixes and improvements, see Recent Changes below.
- 2008-04-07: Version 1.1. Fix problems with images and attachments with no wiki:PageName, now it should work.
There are several dependencies:
- xhtml2pdf and PISA: The python library used to convert HTML to PDF. You can install it with easy_install pisa. The version supported by this plugin is 3.0.32. Others might work (3.0.29 is known to have a bug in TOC creation).
- ReportLab version 2.2: This is a dependency of xhtml2pdf. If using easy_install, it should be automatically installed.
- HTML5lib: Same as previous.
- pyPDF: Same as previous.
- PIL (Python Imaging Library): I'm not sure if this is a dependency of xhtml2pdf, but anyways, easy_install PIL should do the work.
- Pygments: Python syntax highlighter. You need this for syntax highlighting in Trac, too.
To install dependencies (PIL/!ReportLab/HTML5Lib/Pygments/pyPDF):
aptitude install python-imaging python-reportlab python-html5lib python-pygments python-pypdf
yum install python-imaging python-reportlab python-html5lib python-pygments pyPdf
To install plugin:
Enable the plugin by adding wikiprint.* = enabled in the components section of the trac.ini file:
[components] ... wikiprint.* = enabled
When enabled, two new administrative panels will be available under the Wikiprint section, and 3 new formats will be available in the Download in other formats section at the end of the wiki page:
- PDF Article
- PDF Book
- Printable HTML
If you're behind a proxy, add something like this to your .wsgi file so remote resources can be downloaded when creating pdfs:
import os os.environ['http_proxy'] = 'http://myproxy.company.com:8080' os.environ['no_proxy'] = '.company.com'
If you're using apache with authentication, add something like this to your apache .conf file so local resources can be downloaded when creating pdfs (where
your.ip.address is replaced with the output of
... Require valid-user Order deny,allow Deny from all Allow from 127.0.0.1 Allow from your.ip.address Satisfy any ...
Additional options can be set by creating a wikiprint section in trac.ini:
[wikiprint] toc_title = Table of Contents #CSS and content files (or URLS, using http://...) css_url = c:/path/to/file.css article_css_url = c:/path/to/article.css book_css_url = c:/path/to/book.css frontpage_url = c:/path/to/frontpage.html extracontent_url = c:/path/to/extracontent.html rebase_links = http://anotherserver.com/path omit_links = False httpauth_user = wikiprint_user httpauth_password = *password*
Most of these options can be also set from the web administrative interface:
Not available in administrative interface yet:
- rebase_links: When generating PDF or printable HTML, change the base URL to the base URL specified with this option. Useful for changing local references (something like "http://localhost:8080") to a global address (like http://mycompany.com/trac).
- omit_links: Remove internal wiki links from generated PDFs.
- omit_macros: A comma separated list of macro names that will be omited when converting the wiki document to the selected output (PDF or printable HTML).
xhtml2pdf special tags and styles
WikiPrint works by converting one or some Wiki pages to HTML, adding some CSS styles and replacing special tags, and then passing the output to the xhtml2pdf library, so in order to understand how to customize the output using CSS, and to use some special html tags used by xhtml2pdf, you'll have to check the xhtml2pdf manual.
Also, check the default css and extra_content files, as they provide usage examples. To see the contents of the default files, leave the corresponding field blank in the administration panel, and click the View button.
Images and links
WikiPrint exports the wiki format to HTML first, then converts the HTML to PDF using xhtml2pdf library. Links and image references in the wiki to html conversion are made as absolute URLS.
In order to generate the PDF, xhtml2pdf library will try to download the images from their absolute URL (exactly as your web browser would do).
For example, if you access the trac project from your browser using the URL http://myserver/trac/myproject, but address of myserver is locally resolved at your workstation (via /etc/hosts or similar), and not globally known, then xhtml2pdf will fail to resolve myserver and won't be able to download the images from http://myserver/trac/myproject/. In that case, use the server IP instead.
Authentication and permissions
When using cookie based authentication (like AccountManager), the xhtml2pdf library is given a temporary cookie to authenticate in behave of the user, so the conversion process will have the same permissions as the user downloading the .pdf, but you must make sure that the project URL is accessible locally from the trac server itself.
Optionally, is HTTP Basic or Digest authentication is used, wikiprint can be configured to log in using httpauth_user and httpauth_password options.
Wikiprint defines three new permissions:
- WIKIPRINT_ADMIN: Allow users to acces the Wikiprint Options admin page, and configure wikiprint options.
- WIKIPRINT_BOOK: Allow users to access the Make Book admin page.
- WIKIPRINT_FILESYSTEM: When setting up header, footer, style, etc. the user can enter a path to a file from the file system. In order for this to work, the user must have this WIKIPRINT_FILESYSTEM permission. Otherwise, this could mean a security risk, as the user might display /etc/passwd or critical files. This is not a WikiPrint problem, as anyone with TRAC_ADMIN permissions would be able to install and run a potentially insecure plugin. So, make sure you trust users with TRAC_ADMIN permissions, and you give WIKIPRINT_FILESYSTEM permission only to trusted users.
WikiPrint adds several download formats to the bottom of the wiki page. Following is the description of the available formats.
PDF article creates a PDF file out of the wiki page, with no front page. Additional styles will be used from the CSS file defined in article_css option.
If the page uses the [[PageOutline]] macro, it will be replaced by a Table of Contents.
PDF article can be used to combine several wiki pages too, from the administrative interface.
This format will create a book-like PDF document. A front page that can show title, subject, date and version is inserted at the beginning of the document. A 'Table of Contents' is also inserted after the front page. Any further ocurrences of [[PageOutline]] will be removed. Different wiki pages will be separated by a page break.
This is specially useful for combining several wiki pages from the administrative interface:
This option will just convert to wiki text to HTML, and display it in the browser with some styles, so it can be printed directly from the browser.
When enabling the plugin, a new WikiPrint panel will be available in administration. From this panel, you can select a set of pages, and export them to any of the supported formats.
You can specify a Title, Subject, Date and Version for the exported document.
When defining the contents of the front page file (using HTML), or the extra contents file (HTML for header, footer or other frames), some special tags can be used, and they will be replaced before exporting the document.
The following tags are supported:
- #TITLE: Replaced with the Title field when combining pages from the administrative interface, or replaced with the Page Name when exporting from the wiki.
- #SUBJECT: Replaced with the Subject field when combining pages from the administrative interface, or blank when exporting from the wiki.
- #DATE: Replaced with the Date field when combining pages from the administrative interface, or the current time when exporting from the wiki.
- #VERSION: Replaced with the Version field when combining pages from the administrative interface, or the current page version when exporting from the wiki.
WikiPrint allows customization of documents by three different options:
- css_url: A path or URL to a file with CSS styles that will be applied to the exported output. If left blank, a default CSS is used. If you are creating a custom CSS, use the default CSS as start, and change as needed. Some tweaking is needed in order to make xhtml2pdf/PISA library generate PDF correctly.
- article_css_url: A path or URL to a file with CSS styles that will be used only when exporting to PDF Article format. The default one defines the page margins, and creates header and footer frames, which contents will be defined in the extracontent_url file.
- book_css_url: A path or URL to a file with CSS styles that will be used only when exporting to PDF Book format. The default one defines the default page with no header or footer, which will be used for the front page, and a standard templage page, which will be used for successive pages, with header and footer.
Customizing front page, header, footer, contents
- frontpage_url: A path or URL to a file with HTML (It doesn't have to be a well formed xhtml document, so don't include begin/end tags, body, etc., see the default one), that will be used as the front page when exporting to PDF Book. Some special tags can be used to insert the title, version, date, etc. See Tag Replacement
- extracontent_url: A path or URL to a file with HTML that will be inserted at the beginning of the document before passing it to to xhtml2pdf. This should be used to define the contents of the header and footer. See xhtml2html documentation, and the default article CSS contents and default extra contents for an example.
If you have any issues, create a new ticket.
Windows & IIS
If you should need to access the ressources locally and not via web browser (images, fonts), you may try the #9854 hotfix. Now in testing, please keep the ticket updated with results in order to release this.
- 15603 by rjollos on 2016-06-23 19:20:46
2.0.0dev: Refactor code
- Avoid string interpolation in logger
- Fix spelling error
- Separate local import from import of Python packages
- Use context manager to open file
- 15602 by rjollos on 2016-06-23 18:55:09
The attribute isn't supported in setuptools >= 10.
- 14874 by rjollos on 2015-08-12 18:22:03
2.0.0dev: Use Trac 1.0 database API. Fixes #12480.
Patch by sdegrande.
pisa-en.pdf (47.5 KB) - added by 8 years ago.
xhtml2pdf / PISA Manual
admin_screenshot.jpg (78.4 KB) - added by 8 years ago.
WikiPrint Administration screenshot
- admin_makebook.jpg (74.4 KB) - added by 7 years ago.
- admin_options.jpg (93.6 KB) - added by 7 years ago.
Download all attachments as: .zip