Changes between Version 36 and Version 37 of TracWikiPrintPlugin


Ignore:
Timestamp:
Feb 8, 2013 3:04:58 AM (20 months ago)
Author:
anonymous
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracWikiPrintPlugin

    v36 v37  
    11[[PageOutline(2-5,Contents,pullout)]] 
     2 
    23= !WikiPrint Trac Plugin = 
     4== Description == 
     5Make 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] and PISA), instead of depending on an external applications. 
    36 
    4 == Description == 
    5  
    6 Make wiki pages easily printable, exporting to '''PDF''' (book or article format) or printable '''HTML''' format (page contents without trac headers/footers). 
    7  
    8 PDF export is based on [http://www.xhtml2pdf.com/ xhtml2pdf] and PISA pure python libraries, instead of depending on an external application. 
    9  
    10 !WikiPrint features: 
    11  
     7== Features == 
    128 * Fully customizable header/footers for PDF 
    139 * Syntax highlighting in exported format, using pygments 
     
    1814 
    1915== News == 
    20  
    2116 * '''2011-09-26: Version 1.9.2'''. New option ''omit_macros'' to specify a list of macros to be removed on PDF. 
    2217 * '''2011-09-23: Version 1.9.1'''. Included ''omit_links'' and ''rebase_links'' options in .ini section. 
    2318 * '''2011-09-23: Version 1.9'''. Added ''link_format'', ''omit_links'' and ''rebase_links'' options. 
    24  * '''2010-05-05: Version 1.8.3'''. Some fixes, see Recent Changes below.  
     19 * '''2010-05-05: Version 1.8.3'''. Some fixes, see Recent Changes below. 
    2520 * ... 
    2621 * '''2010-02-22: Version 1.8'''. Some fixes and improvements, see Recent Changes below. 
     
    2924 
    3025== Usage instructions == 
     26There are several '''dependencies''': 
    3127 
    32 First, install the plugin as usual. There are several '''dependencies''': 
    33  
    34  * [http://www.xhtml2pdf.com/ 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). 
     28 * [http://www.xhtml2pdf.com/ xhtml2pdf] and [http://pypi.python.org/pypi/pisa 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). 
    3529 * [http://www.reportlab.org/ ReportLab version 2.2]: This is a dependency of xhtml2pdf. If using easy_install, it should be automatically installed. 
    3630 * [http://code.google.com/p/html5lib/ HTML5lib]: Same as previous. 
     
    3933 * [http://pygments.org/ Pygments]: Python syntax highlighter. You need this for syntax highlighting in Trac, too. 
    4034 
    41 For Debian/Fedora based systems, dependencies can be installed with: 
     35To install dependencies (PIL/!!ReportLab/HTML5Lib/Pygments/pyPDF): 
    4236 
    43  * For PIL: aptitude/yum install python-imaging 
    44  * For ReportLab: aptitude/yum install python-reportlab 
    45  * For HTML5Lib: aptitude/yum install python-html5lib 
    46  * For Pygments: aptitude/yum install python-pygments 
     37 * Debian: 
     38   * `aptitude install python-imaging python-reportlab python-html5lib python-pygments python-pypdf` 
     39 * Fedora: 
     40   * `yum install  python-imaging python-reportlab python-html5lib python-pygments pyPdf` 
     41 
     42To install plugin: 
     43 
     44 * `easy_install http://trac-hacks.org/svn/tracwikiprintplugin/0.11` 
    4745 
    4846Enable the plugin by adding '''wikiprint.* = enabled''' in the ''components'' section of the ''trac.ini'' file: 
     
    5351wikiprint.* = enabled 
    5452}}} 
    55  
    5653When 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: 
    5754 
     
    6057 * Printable HTML 
    6158 
     59If you're behind a proxy, add something like this to your .wsgi file so resources can be downloaded when creating pdfs: 
     60 
     61{{{ 
     62import os 
     63os.environ['http_proxy'] = 'http://myproxy.company.com:8080' 
     64os.environ['no_proxy'] = '.company.com' 
     65}}} 
    6266Additional options can be set by creating a ''wikiprint'' section in ''trac.ini'': 
    6367 
     
    7781httpauth_password = *password* 
    7882}}} 
    79  
    8083Most of these options can be also set from the web administrative interface: 
    8184 
     
    8992 
    9093=== Some notes === 
    91  
    9294==== xhtml2pdf special tags and styles ==== 
    93  
    9495!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 [attachment:"pisa-en.pdf" xhtml2pdf manual]. 
    9596 
     
    9798 
    9899==== Images and links ==== 
    99  
    100100!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. 
    101101 
    102 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).  
     102In order to generate the PDF, ''xhtml2pdf'' library will try to download the images from their absolute URL (exactly as your web browser would do). 
    103103 
    104104For 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. 
     
    106106'''Authentication and permissions''' 
    107107 
    108 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'''.  
     108When 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'''. 
    109109 
    110110Optionally, is HTTP Basic or Digest authentication is used, wikiprint can be configured to log in using '''httpauth_user''' and '''httpauth_password''' options. 
    111111 
    112112=== Security Concerns === 
    113  
    114113Wikiprint defines three new permissions: 
    115114 
     
    119118 
    120119=== Export formats === 
    121  
    122120!WikiPrint adds several download formats to the bottom of the wiki page. Following is the description of the available formats. 
    123121 
    124122==== PDF Article ==== 
    125  
    126123PDF 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. 
    127124 
    128 If the page uses the ![[PageOutline]] macro, it will be replaced by a Table of Contents.  
     125If the page uses the ![[PageOutline]] macro, it will be replaced by a Table of Contents. 
    129126 
    130127PDF article can be used to combine several wiki pages too, from the administrative interface. 
    131128 
    132129==== PDF Book ==== 
    133  
    134130This 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. 
    135131 
     
    139135 
    140136==== Printable HTML ==== 
    141  
    142137This 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. 
    143138 
    144139=== Combining pages === 
    145  
    146140When 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. 
    147141 
     
    149143 
    150144=== Tag replacement === 
    151  
    152 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.  
     145When 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. 
    153146 
    154147The following tags are supported: 
     
    160153 
    161154=== Customizing styles === 
    162  
    163155!WikiPrint allows customization of documents by three different options: 
    164156 
    165157 * '''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. 
    166  * '''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.  
     158 * '''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. 
    167159 * '''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. 
    168160 
     
    170162 
    171163=== Customizing front page, header, footer, contents === 
    172  
    173164 * '''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'' 
    174165 * '''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. 
    175166 
    176 == Bugs/Feature Requests ==  
     167== Bugs/Feature Requests == 
     168Existing bugs and feature requests for TracWikiPrintPlugin are  [report:9?COMPONENT=TracWikiPrintPlugin here]. 
    177169 
    178 Existing bugs and feature requests for TracWikiPrintPlugin are  
    179 [report:9?COMPONENT=TracWikiPrintPlugin here]. 
    180  
    181 If you have any issues, create a  
    182 [http://trac-hacks.org/newticket?component=TracWikiPrintPlugin&owner=airadier new ticket]. 
     170If you have any issues, create a  [http://trac-hacks.org/newticket?component=TracWikiPrintPlugin&owner=airadier new ticket]. 
    183171 
    184172== Download == 
    185  
    186 Download the zipped source from [download:tracwikiprintplugin here]. 
    187 In addition to official Debian packages, there is an  
    188 [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935-0.1_all.deb unofficial Debian package]  
    189 (with [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935.orig.tar.gz src],  
    190 [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935-0.1.dsc dsc], and  
    191 [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935-0.1.debian.tar.gz debian changes]). 
     173Download the zipped source from [download:tracwikiprintplugin here]. In addition to official Debian packages, there is an  [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935-0.1_all.deb unofficial Debian package]  (with [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935.orig.tar.gz src],  [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935-0.1.dsc dsc], and  [http://dl.dropbox.com/u/4213259/deb/trac-wikiprint_1.8.4%2Br7935-0.1.debian.tar.gz debian changes]). 
    192174 
    193175== Source == 
    194  
    195176You can check out TracWikiPrintPlugin from [http://trac-hacks.org/svn/tracwikiprintplugin here] using Subversion, or [source:tracwikiprintplugin browse the source] with Trac. 
    196177 
     
    200181 
    201182== Recent Changes == 
    202  
    203183[[ChangeLog(tracwikiprintplugin, 3)]] 
    204184 
    205185== Author/Contributors == 
    206  
    207 '''Author:''' [wiki:airadier] [[BR]] 
    208 '''Maintainer:''' [wiki:airadier] [[BR]] 
    209 '''Contributors:''' 
     186'''Author:''' [wiki:airadier] [[BR]] '''Maintainer:''' [wiki:airadier] [[BR]] '''Contributors:'''