Changes between Version 39 and Version 40 of TracWikiPrintPlugin


Ignore:
Timestamp:
May 19, 2015, 6:57:05 PM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes, tagged with license

Legend:

Unmodified
Added
Removed
Modified

  • TracWikiPrintPlugin

    v39 v40  
    11[[PageOutline(2-5,Contents,pullout)]]
    22
    3 = !WikiPrint Trac Plugin =
    4 == Description ==
    5 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 [http://www.xhtml2pdf.com/ xhtml2pdf] and PISA), instead of depending on an external applications.
    6 
    7 == Features ==
    8  * Fully customizable header/footers for PDF
    9  * Syntax highlighting in exported format, using pygments
    10  * Customizable front page for PDF book format
    11  * Automatic creation of Table of Contents if ![[PageOutline]] or ![[TOC]] Macro is used
     3= !WikiPrint Trac Plugin
     4
     5== Description
     6
     7This plugin allows you to 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 [http://www.xhtml2pdf.com/ xhtml2pdf], instead of depending on an external applications.
     8
     9Key features:
     10 * Fully customizable header/footers for PDF.
     11 * Syntax highlighting in exported format, using Pygments.
     12 * Customizable front page for PDF book format.
     13 * Automatic creation of Table of Contents if ![[PageOutline]] or ![[TOC]] Macro is used.
    1214 * The style of the resulting PDF or HTML can be fully customized using CSS files.
    1315
    14 == News ==
    15  * '''2013-02-07: Wiki'''. Cleaned up page and added more useful information.
    16  * '''2011-09-26: Version 1.9.2'''. New option ''omit_macros'' to specify a list of macros to be removed on PDF.
    17  * '''2011-09-23: Version 1.9.1'''. Included ''omit_links'' and ''rebase_links'' options in .ini section.
    18  * '''2011-09-23: Version 1.9'''. Added ''link_format'', ''omit_links'' and ''rebase_links'' options.
    19  * '''2010-05-05: Version 1.8.3'''. Some fixes, see Recent Changes below.
    20  * ...
    21  * '''2010-02-22: Version 1.8'''. Some fixes and improvements, see Recent Changes below.
    22  * ...
    23  * '''2008-04-07: Version 1.1'''. Fix problems with images and attachments with no !wiki:PageName, now it should work.
    24 
    25 == Install ==
     16== Bugs/Feature Requests
     17
     18Existing bugs and feature requests for TracWikiPrintPlugin are [report:9?COMPONENT=TracWikiPrintPlugin here].
     19
     20If you have any issues, create a  [http://trac-hacks.org/newticket?component=TracWikiPrintPlugin&owner=airadier new ticket].
     21
     22[[TicketQuery(component=TracWikiPrintPlugin&group=type,format=progress)]]
     23
     24== Download
     25
     26Download 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]).
     27
     28== Source
     29
     30You can check out TracWikiPrintPlugin from [http://trac-hacks.org/svn/tracwikiprintplugin here] using Subversion, or [source:tracwikiprintplugin browse the source] with Trac.
     31
     32=== Patches
     33
     34If you are running Windows & IIS and you should 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.
     35
     36== Installation
     37
    2638There are several '''dependencies''':
    2739
    … …  
    4456 * `easy_install http://trac-hacks.org/svn/tracwikiprintplugin/0.11`
    4557
    46 Enable the plugin by adding '''wikiprint.* = enabled''' in the ''components'' section of the ''trac.ini'' file:
    47 
    48 {{{
     58Enable the plugin by adding '''wikiprint.* = enabled''' in the ''components'' section of your `trac.ini` file:
     59
     60{{{#!ini
    4961[components]
    5062...
    … …  
    5769 * Printable HTML
    5870
    59 == Settings ==
     71== Settings
     72
    6073If you're behind a '''proxy''', add something like this to your .wsgi file so '''remote''' resources can be downloaded when creating pdfs:
    6174
    62 {{{
     75{{{#!python
    6376import os
    6477os.environ['http_proxy'] = 'http://myproxy.company.com:8080'
    6578os.environ['no_proxy'] = '.company.com'
    6679}}}
     80
    6781If 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 `hostname -i`):
    6882
    69 {{{
     83{{{#!apache
    7084...
    7185 Require valid-user
    … …  
    7791...
    7892}}}
    79 Additional options can be set by creating a ''wikiprint'' section in ''trac.ini'' (you can specify either local paths or remote urls for css and html files):
    80 
    81 {{{
     93Additional options can be set by creating a ''wikiprint'' section in your `trac.ini` file:
     94
     95{{{#!ini
    8296[wikiprint]
    8397toc_title = Table of Contents
    … …  
    93107omit_links = false
    94108}}}
     109
     110You can specify either local paths or remote urls for css and html files.
     111
    95112Most of these options can be also set from the web administrative interface:
    96113
    97114[[Image(wiki:TracWikiPrintPlugin:admin_options.jpg, 60%, border=1)]]
    98115
    99 === Customizing styles ===
     116=== Customizing styles
     117
    100118!WikiPrint allows customization of documents by three different options:
    101119
    … …  
    106124For more information about the styles that affect the PDF output, see the [attachment:"pisa-en.pdf" xhtml2pdf  manual].
    107125
    108 === Customizing front page, header, footer, contents ===
     126=== Customizing front page, header, footer, contents
     127
    109128 * '''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''
    110129 * '''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.
    111130
    112 === Authentication ===
     131=== Authentication
     132
    113133When 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'''.
    114134
    115135Optionally, is HTTP Basic or Digest authentication is used, wikiprint can be configured to log in using '''httpauth_user''' and '''httpauth_password''' options.
    116136
    117 === Not available in administrative interface yet: ===
     137Not available in administrative interface yet:
     138
    118139 * '''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).
    119140 * '''omit_links''': Remove internal wiki links from generated PDFs.
    120141 * '''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).
    121142
    122 == Permissions ==
     143== Permissions
     144
    123145Wikiprint defines three new permissions:
    124146
    … …  
    127149 * 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.
    128150
    129 == Exporting and formats ==
     151== Exporting and formats
     152
    130153!WikiPrint adds several download formats to the bottom of the wiki page. Following is the description of the available formats.
    131154
    132 === PDF Article ===
     155=== PDF Article
     156
    133157PDF 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.
    134158
    … …  
    137161PDF article can be used to combine several wiki pages too, from the administrative interface.
    138162
    139 === PDF Book ===
     163=== PDF Book
     164
    140165This 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.
    141166
    … …  
    144169[[Image(wiki:TracWikiPrintPlugin:admin_makebook.jpg, 60%, border=1)]]
    145170
    146 === Printable HTML ===
     171=== Printable HTML
     172
    147173This 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.
    148174
    149 === Combining pages ===
     175=== Combining pages
     176
    150177When 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.
    151178
    152179You can specify a Title, Subject, Date and Version for the exported document.
    153180
    154 === Tag replacement ===
     181=== Tag replacement
     182
    155183When 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.
    156184
    … …  
    162190 * #VERSION: Replaced with the ''Version'' field when combining pages from the administrative interface, or the current page version when exporting from the wiki.
    163191
    164 == Notes ==
    165 === xhtml2pdf special tags and styles ===
     192== Notes
     193
     194=== xhtml2pdf special tags and styles
     195
    166196!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].
    167197
    168198Also, 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.
    169199
    170 === Images and links ===
     200=== Images and links
     201
    171202!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.
    172203
    … …  
    175206For 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.
    176207
    177 == Bugs/Feature Requests ==
    178 Existing bugs and feature requests for TracWikiPrintPlugin are  [report:9?COMPONENT=TracWikiPrintPlugin here].
    179 
    180 If you have any issues, create a  [http://trac-hacks.org/newticket?component=TracWikiPrintPlugin&owner=airadier new ticket].
    181 
    182 == Download ==
    183 Download 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]).
    184 
    185 == Source ==
    186 You can check out TracWikiPrintPlugin from [http://trac-hacks.org/svn/tracwikiprintplugin here] using Subversion, or [source:tracwikiprintplugin browse the source] with Trac.
    187 
    188 == Patches ==
    189 === Windows & IIS ===
    190 If you should 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.
    191 
    192 == Recent Changes ==
     208== Recent Changes
     209
    193210[[ChangeLog(tracwikiprintplugin, 3)]]
    194211
    195 == Author/Contributors ==
    196 '''Author:''' [wiki:airadier] [[BR]] '''Maintainer:''' [wiki:airadier] [[BR]] '''Contributors:''' (always welcome!)
     212== Author/Contributors
     213
     214'''Author:''' [wiki:airadier] [[BR]]
     215'''Maintainer:''' [[Maintainer]] [[BR]]
     216'''Contributors:''' (always welcome!)