Changes between Initial Version and Version 1 of TracWikiPrintPlugin/WikiPrintXhtml2pdf

Timestamp:

May 20, 2021, 7:02:51 AM (3 years ago)

Author:

Cinc-th

Comment:

Move current description to a separate page because current trunk no longer uses xhtml2pdf and has a different feature set.

TracWikiPrintPlugin/WikiPrintXhtml2pdf

@@ +1 @@
+[[PageOutline(2-5,Contents,pullout)]]
+
+= Make Trac wiki pages printable
+
+== Description
+
+This plugin allows you to make Trac 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 [http://www.xhtml2pdf.com/ xhtml2pdf], instead of depending on external applications.
+
+Key features:
+ * Fully customizable header/footers for PDF.
+ * Syntax highlighting in exported format, using [http://pygments.org/ 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.
+
+See also TracWikiToPdfPlugin.
+
+== 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].
+
+=== Patches
+
+If you are running Windows with the IIS web server and you need to access resources 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.
+
+== Installation
+
+The syntax highlighting library [http://pygments.org/ Pygments] is optional.
+
+To install the plugin:
+
+{{{#!sh
+$ pip install https://trac-hacks.org/svn/tracwikiprintplugin/1.0
+}}}
+
+Enable the plugin by adding '''wikiprint.* = enabled''' in the ''components'' section of your `trac.ini` file:
+
+{{{#!ini
+[components]
+...
+wikiprint.* = enabled
+}}}
+
+After 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
+
+== Configuration
+
+If you are behind a '''proxy''', add something like this to your .wsgi file so '''remote''' resources can be downloaded when creating pdfs:
+
+{{{#!python
+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 to be replaced with the output of `hostname -i`:
+
+{{{#!apache
+...
+ 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 your `trac.ini` file:
+
+{{{#!ini
+[wikiprint]
+toc_title = Table of Contents
+css_url = /path/to/file.css
+article_css_url = /path/to/article.css
+book_css_url = /path/to/book.css
+frontpage_url = /path/to/frontpage.html
+extracontent_url = /path/to/extracontent.html
+httpauth_user = wikiprint_user
+httpauth_password = *password*
+
+rebase_links = http://anotherserver.com/path
+omit_links = false
+}}}
+
+You can specify either local paths or remote urls for css and html files.
+
+Most of these options can be also set from the web administrative interface:
+
+[[Image(wiki:TracWikiPrintPlugin:admin_options.jpg, border=2)]]
+
+=== Customizing styles
+
+!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 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.
+
+For more information about the styles that affect the PDF output, see the [attachment:"pisa-en.pdf" xhtml2pdf manual].
+
+=== 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.
+
+=== Authentication
+
+When using cookie based authentication, like AccountManager, the ''xhtml2pdf'' library is given a temporary cookie to authenticate 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, if HTTP Basic or Digest authentication is used, Wikiprint can be configured to log in using '''httpauth_user''' and '''httpauth_password''' options.
+
+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 omitted when converting the wiki document to the selected output (PDF or printable HTML).
+
+== Permissions
+
+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. For this to work, the user must have this `WIKIPRINT_FILESYSTEM` permission. Otherwise, this could pose 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 give `WIKIPRINT_FILESYSTEM` permission only to trusted users.
+
+== Exporting and formats
+
+!WikiPrint adds several download formats to the bottom of the wiki page. Following is the description of the available formats.
+
+=== PDF Article
+
+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.
+
+=== PDF Book
+
+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 occurrences 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:
+
+[[Image(wiki:TracWikiPrintPlugin:admin_makebook.jpg, border=2)]]
+
+=== Printable HTML
+
+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.
+
+=== Combining pages
+
+When enabling the plugin, a new !WikiPrint panel will be available in the administration panel. 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.
+
+=== Tag replacement
+
+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.
+
+== Notes
+
+=== 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 [wiki:TracWikiPrintPlugin:attachment:pisa-en.pdf 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 the xhtml2pdf library. Links and image references in the wiki to html conversion are made as absolute URLS.
+
+To generate the PDF, the ''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 the 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.
+
+== Recent Changes
+
+[[ChangeLog(tracwikiprintplugin, 3)]]
+
+== Author/Contributors
+
+'''Author:''' [wiki:airadier] [[BR]] 
+'''Maintainer:''' [[Maintainer(TracWikiPrintPlugin)]] [[BR]] 
+'''Contributors:''' sdegrande