Changes between Version 42 and Version 43 of TracWikiPrintPlugin


Ignore:
Timestamp:
Nov 19, 2015, 11:47:33 AM (8 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • TracWikiPrintPlugin

    v42 v43  
    55== Description
    66
    7 This 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.
     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 external applications.
    88
    99Key features:
    1010 * Fully customizable header/footers for PDF.
    11  * Syntax highlighting in exported format, using Pygments.
     11 * Syntax highlighting in exported format, using [http://pygments.org/ Pygments].
    1212 * Customizable front page for PDF book format.
    1313 * Automatic creation of Table of Contents if ![[PageOutline]] or ![[TOC]] Macro is used.
    … …  
    2424== Download
    2525
    26 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]).
     26Download the zipped source from [export: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]).
    2727
    2828== Source
    2929
    30 You can check out TracWikiPrintPlugin from [http://trac-hacks.org/svn/tracwikiprintplugin here] using Subversion, or [source:tracwikiprintplugin browse the source] with Trac.
     30You can check out TracWikiPrintPlugin from [/svn/tracwikiprintplugin here] using Subversion, or [source:tracwikiprintplugin browse the source] with Trac.
    3131
    3232=== Patches
    3333
    34 If you are running Windows & IIS 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.
     34If 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.
    3535
    3636== Installation
    … …  
    4545 * [http://pygments.org/ Pygments]: Python syntax highlighter. You need this for syntax highlighting in Trac too.
    4646
    47 To install dependencies (PIL/!!ReportLab/HTML5Lib/Pygments/pyPDF):
     47To install dependencies (PIL/!ReportLab/HTML5Lib/Pygments/pyPDF):
    4848
    4949 * On Debian/Ubuntu:
    … …  
    5454To install plugin:
    5555
    56  * `easy_install http://trac-hacks.org/svn/tracwikiprintplugin/0.11`
     56 * `easy_install https://trac-hacks.org/svn/tracwikiprintplugin/0.11`
    5757
    5858Enable the plugin by adding '''wikiprint.* = enabled''' in the ''components'' section of your `trac.ini` file:
    … …  
    8080}}}
    8181
    82 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 `hostname -i`):
     82If 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`):
    8383
    8484{{{#!apache
    … …  
    120120!WikiPrint allows customization of documents by three different options:
    121121
    122  * '''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.
     122 * '''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.
    123123 * '''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.
    124124 * '''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.
    … …  
    128128=== Customizing front page, header, footer, contents
    129129
    130  * '''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''
     130 * '''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''
    131131 * '''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.
    132132
    133133=== Authentication
    134134
    135 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'''.
    136 
    137 Optionally, is HTTP Basic or Digest authentication is used, wikiprint can be configured to log in using '''httpauth_user''' and '''httpauth_password''' options.
     135When 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'''.
     136
     137Optionally, if HTTP Basic or Digest authentication is used, Wikiprint can be configured to log in using '''httpauth_user''' and '''httpauth_password''' options.
    138138
    139139Not available in administrative interface yet:
    … …  
    141141 * '''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).
    142142 * '''omit_links''': Remove internal wiki links from generated PDFs.
    143  * '''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).
     143 * '''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).
    144144
    145145== Permissions
    … …  
    147147Wikiprint defines three new permissions:
    148148
    149  * WIKIPRINT_ADMIN: Allow users to acces the ''Wikiprint Options'' admin page, and configure wikiprint options.
    150  * WIKIPRINT_BOOK: Allow users to access the ''Make Book'' admin page.
    151  * 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 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 give WIKIPRINT_FILESYSTEM permission only to trusted users.
     149 * `WIKIPRINT_ADMIN`: Allow users to acces the ''Wikiprint Options'' admin page, and configure wikiprint options.
     150 * `WIKIPRINT_BOOK`: Allow users to access the ''Make Book'' admin page.
     151 * `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.
    152152
    153153== Exporting and formats
    … …  
    165165=== PDF Book
    166166
    167 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.
     167This 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.
    168168
    169169This is specially useful for combining several wiki pages from the administrative interface:
    … …  
    177177=== Combining pages
    178178
    179 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.
     179When 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.
    180180
    181181You can specify a Title, Subject, Date and Version for the exported document.
    … …  
    202202=== Images and links
    203203
    204 !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.
    205 
    206 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).
    207 
    208 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.
     204!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.
     205
     206To generate the PDF, the ''xhtml2pdf'' library will try to download the images from their absolute URL, exactly as your web browser would do.
     207
     208For 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.
    209209
    210210== Recent Changes