Changes between Version 55 and Version 56 of TracWikiPrintPlugin


Ignore:
Timestamp:
May 21, 2021, 10:26:10 AM (3 years ago)
Author:
Cinc-th
Comment:

Documented current plugin features. Links to older description covering V3.0.0 and older are included.

Legend:

Unmodified
Added
Removed
Modified

  • TracWikiPrintPlugin

    v55 v56  
    55== Description
    66
    7 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.
     7This plugin allows you to export to PDF (book or article format) or printable HTML format (page contents without Trac headers/footers) allowing easy printing. PDF export is based on [https://wkhtmltopdf.org/ wkhtmltopdf].
     8
     9Older versions up to V3.0.0 used [http://www.xhtml2pdf.com/ xhtml2pdf] for generating PDF files. While having the advantage of being a pure Python solution it was abandoned because the output quality of [https://wkhtmltopdf.org/ wkhtmltopdf] is way better. For these unsupported older releases see [wiki:TracWikiPrintPlugin/WikiPrintXhtml2pdf WikiPrintXhtml2pdf].
    810
    911Key features:
    10  * Fully customizable header/footers for PDF.
    11  * Syntax highlighting in exported format, using [http://pygments.org/ Pygments].
    12  * Customizable front page for PDF book format.
    13  * Automatic creation of Table of Contents if `[[PageOutline]]` or `[[TOC]]` macro is used.
    14  * The style of the resulting PDF or HTML can be fully customized using CSS files.
    15 
    16 See also TracWikiToPdfPlugin.
     12
     13* Administration page for default settings.
     14* Customizable footers for PDF.
     15* Customizable front page for PDF book format.
     16* Automatic creation of Table of Contents for PDF books.
     17* The style of the resulting PDF or HTML can be fully customized using CSS.
     18* Different page sizes.
     19* PDF "print dialog" for altering settings prior to PDF file creation.
     20* Makro to specify contents and format of PDF Books with export feature.
     21
     22The plugin is seamlessly integrated in the Trac user interface by adding items to the `Download in other formats` section of each wiki page.
     23
     24
     25See also
     26* TracWikiToPdfPlugin
     27* [wiki:TracWikiPrintPlugin/WikiPrintXhtml2pdf WikiPrintXhtml2pdf]
     28
     29
     30=== Supported Trac releases
     31
     32Trac 1.4 and 1.6 are fully supported.
     33
     34For older releases use TracWikiPrintPlugin V3.x.x or older. See [wiki:TracWikiPrintPlugin/WikiPrintXhtml2pdf WikiPrintXhtml2pdf] for more information.
     35
     36== License
     37
     38Releases up to {{{V3.x.x}}} were licensed as GPL.
     39
     40With {{{V4.0.0}}} the plugin was rewritten from scratch and is now BSD licensed.
    1741
    1842== Bugs/Feature Requests
    … …  
    3458The plugin is also available on [pypi:TracWikiPrint PyPi].
    3559
    36 === Patches
    37 
    38 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.
    3960
    4061== Installation
    4162
    42 The syntax highlighting library [http://pygments.org/ Pygments] is optional.
    43 
    44 To install the plugin:
     63To install the plugin from trunk:
    4564
    4665{{{#!sh
    47 $ pip install https://trac-hacks.org/svn/tracwikiprintplugin/1.0
    48 }}}
    49 
    50 Enable the plugin by adding '''wikiprint.* = enabled''' in the ''components'' section of your `trac.ini` file:
     66$ pip install https://trac-hacks.org/svn/tracwikiprintplugin/trunk
     67}}}
     68
     69To install the older `V3.0.0` release:
     70
     71{{{#!sh
     72$ pip install https://trac-hacks.org/svn/tracwikiprintplugin/tags/V3.0.0
     73}}}
     74
     75Install [https://wkhtmltopdf.org/ wkhtmltopdf].
     76
     77**Note:** `wkhtmltopdf` must be in your path or more precisely in the path used by Trac.
     78
     79Enable the plugin using Tracs plugin administration page or by adding `wikiprint.* = enabled` in the ''components'' section of your `trac.ini` file:
    5180
    5281{{{#!ini
    … …  
    5685}}}
    5786
    58 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:
    59 
    60  * PDF Article
    61  * PDF Book
    62  * Printable HTML
    6387
    6488== Configuration
    6589
    66 If you are behind a '''proxy''', add something like this to your .wsgi file so '''remote''' resources can be downloaded when creating pdfs:
    67 
    68 {{{#!python
    69 import os
    70 os.environ['http_proxy'] = 'http://myproxy.company.com:8080'
    71 os.environ['no_proxy'] = '.company.com'
    72 }}}
    73 
    74 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`:
    75 
    76 {{{#!apache
    77 ...
    78  Require valid-user
    79  Order deny,allow
    80  Deny from all
    81  Allow from 127.0.0.1
    82  Allow from your.ip.address
    83  Satisfy any
    84 ...
    85 }}}
    86 
    87 Additional options can be set by creating a ''wikiprint'' section in your `trac.ini` file:
     90Configuration can be done using the new administration page `Page Parameters` in section `Wikiprint`.
     91
     92The settings can also be specified in `trac.ini`:
    8893
    8994{{{#!ini
    9095[wikiprint]
    91 toc_title = Table of Contents
    92 css_url = /path/to/file.css
    93 article_css_url = /path/to/article.css
    94 book_css_url = /path/to/book.css
    95 frontpage_url = /path/to/frontpage.html
    96 extracontent_url = /path/to/extracontent.html
    97 httpauth_user = wikiprint_user
    98 httpauth_password = *password*
    99 
    100 rebase_links = http://anotherserver.com/path
    101 omit_links = false
    102 }}}
    103 
    104 You can specify either local paths or remote urls for css and html files.
    105 
    106 Most of these options can be also set from the web administrative interface:
    107 
    108 [[Image(wiki:TracWikiPrintPlugin:admin_options.jpg, border=2)]]
    109 
    110 === Customizing styles
    111 
    112 !WikiPrint allows customization of documents by three different options:
    113 
    114  * '''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.
    115  * '''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.
    116  * '''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.
    117 
    118 For more information about the styles that affect the PDF output, see the [attachment:"pisa-en.pdf" xhtml2pdf manual].
    119 
    120 === Customizing front page, header, footer, contents
    121 
    122  * '''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''.
    123  * '''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.
    124 
    125 === Authentication
    126 
    127 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'''.
    128 
    129 Optionally, if HTTP Basic or Digest authentication is used, Wikiprint can be configured to log in using '''httpauth_user''' and '''httpauth_password''' options.
    130 
    131 Not available in administrative interface yet:
    132 
    133  * '''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`).
    134  * '''omit_links''': Remove internal wiki links from generated PDFs.
    135  * '''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).
     96# Name of a wiki page used as the cover for a PDF book
     97coverpage = CoverPageInWiki
     98
     99# One of the predfined footers to be added to a PDF. Leave empty for
     100# no footer.
     101#
     102# Available footers:
     103# 1: [page] / [topage]
     104# 2: {pagename}  -  [page] / [topage]
     105footertext = [page] / [topage]
     106
     107# One of the predefined page sizes: A3, A4, A5, B4, B5, B6, Folio, Legal, Letter
     108pagesize = A4
     109
     110# Name of a wiki page containing CSS style information.
     111# A style page must be located below WikiPrint/Styles/
     112# If left empty Tracs default wiki styles are used.
     113stylepage = WikiPrint/Styles/StylePage
     114
     115# Title to be used in the PDF properties. If left empty
     116# the wiki page name will be used
     117title =
     118
     119# Whether to include a table of content in a PDF book
     120toc = enabled|disabled
     121}}}
     122
    136123
    137124== Permissions
    138125
    139 Wikiprint defines three new permissions:
    140 
    141  * `WIKIPRINT_ADMIN`: Allow users to acces the ''Wikiprint Options'' admin page, and configure wikiprint options.
    142  * `WIKIPRINT_BOOK`: Allow users to access the ''Make Book'' admin page.
    143  * `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.
    144 
    145 == Exporting and formats
    146 
    147 !WikiPrint adds several download formats to the bottom of the wiki page. Following is the description of the available formats.
    148 
    149 === PDF Article
    150 
    151 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.
    152 
    153 If the page uses the ![[PageOutline]] macro, it will be replaced by a Table of Contents.
    154 
    155 PDF article can be used to combine several wiki pages too, from the administrative interface.
     126Wikiprint defines a new permission:
     127
     128 * `WIKIPRINT_ADMIN`: Allow users to access the `Page Parameters` admin page, and configure wikiprint default settings.
     129
     130To actually view a wiki page and export it to PDF the user must have `WIKI_VIEW` permission.
     131
     132== Usage
     133
     134After the plugin is enabled, a new administration panel will be available under the `Wikiprint` section, and 4 new download formats will be available in the `Download in other formats` section at the end of each wiki page:
     135
     136* Printable HTML
     137* PDF Page
     138* PDF Page (custom settings)
     139* PDF Book
     140
     141A new makro `PdfBook` can be used to create PDF books from any number of wiki pages.
     142
     143=== Administration page
     144
     145The default configuration for page exports may be provided using the `Wikiprint` administration page. These settings apply when not overriden by the user while exporting a PDF. While most settings are related to PDF files the style page specified here also applies when generating the `Printable HTML` page.
     146
     147
     148=== Printable HTML
     149
     150The wiki page is stripped from Tracs footer, header and navigation. The resulting page only contains the wiki content.
     151
     152Styling of the page is according to the style page selected using the administration panel.
     153
     154
     155=== PDF Page
     156
     157`PDF Page` creates a PDF file out of the wiki page, with no cover page. Styles will be used from the style page defined in the global configuration set with the administration panel.
     158
     159Table of contents macros in the wiki page like `[[PageOutline()]]` or others are not stripped from the page.
     160
     161=== PDF Page (custom settings)
     162
     163The wiki page is exported as a PDF file. This is like normal `PDF Page` export but it is possible to override the global configuration while generating the PDF file. A settings page similar to a "print dialog" is presented to the user before the actual export happens.
     164
    156165
    157166=== PDF Book
    158167
    159 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.
    160 
    161 This is specially useful for combining several wiki pages from the administrative interface:
    162 
    163 [[Image(wiki:TracWikiPrintPlugin:admin_makebook.jpg, border=2)]]
    164 
    165 === Printable HTML
    166 
    167 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.
    168 
    169 === Combining pages
    170 
    171 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.
    172 
    173 You can specify a Title, Subject, Date and Version for the exported document.
    174 
    175 === Tag replacement
    176 
    177 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.
    178 
    179 The following tags are supported:
    180 
    181  * #TITLE: Replaced with the ''Title'' field when combining pages from the administrative interface, or replaced with the Page Name when exporting from the wiki.
    182  * #SUBJECT: Replaced with the ''Subject'' field when combining pages from the administrative interface, or blank when exporting from the wiki.
    183  * #DATE: Replaced with the ''Date'' field when combining pages from the administrative interface, or the current time when exporting from the wiki.
    184  * #VERSION: Replaced with the ''Version'' field when combining pages from the administrative interface, or the current page version when exporting from the wiki.
    185 
    186 == Notes
    187 
    188 === xhtml2pdf special tags and styles
    189 
    190 !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].
    191 
    192 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.
    193 
    194 === Images and links
    195 
    196 !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.
    197 
    198 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.
     168This will create a book-like PDF document. While exporting the user is presented with a settings page to specify a cover page and whether a table of contents should be added. Styling may be changed by selecting one of the available style pages. The cover page used for the book may be any wiki page.
     169
     170Common table of contents macros in the wiki page like `[[PageOutline()]]` or `[[TracGuideToc()]]` are removed from each wiki page.
     171
     172Each book starts with the cover page (if any) directly followed by the table of contents (if enabled).
     173
     174=== PdfBook makro
     175
     176Using the makro it is possible to define PDF books with any number of wiki pages a cover page and table of contents. The configuration specified in the makro may always be overriden by the user while creating the book. This way one may for example change the predefined cover page or omitt the table of contents. Note that you can't add or remove pages while creating the book.
     177
     178The configuration from the makro is rendered to the user and a button added to create the PDF book. Note that only one PdfBook makro on a wiki page is supported.
     179
     180The makro must be specified in WikiProcessors syntax:
     181
     182{{{
     183{{{#!PdfBook
     184...
     185}}}
     186}}}
     187
     188The contents must be formatted like an INI file. The following sections are defined:
     189
     190* `[parameters]`: specify cover page and table of contents
     191* `[pages]`: list of wiki pages to add to the book.
     192
     193{{{
     194{{{#!PdfBook
     195[parameters]
     196# Name of a wiki page to be used as the cover page
     197cover = CoverPage
     198# Set to 1 for a table of contents, else set to 0
     199toc = 1
     200
     201[pages]
     202# Names of wiki pages to be added to the PDF book.
     203WikiStart
     204WikiFormatting
     205}}}
     206}}}
     207
     208
     209=== Custom styling
     210
     211It is possible to use styles different to Tracs default CSS. A wiki page must be created below {{{WikiPrint/Styles/}}} containing the styles to use.
     212
     213For example
     214{{{
     215WikiPrint/Styles/StylePage
     216}}}
     217
     218The page will automatically be available for selection when creating PDF files and on the administration page.
     219
    199220
    200221== Recent Changes
    … …  
    204225== Author/Contributors
    205226
    206 '''Author:''' [wiki:airadier] [[BR]]
     227'''Author:''' [wiki:Cinc-th] [[BR]]
    207228'''Maintainer:''' [[Maintainer]] [[BR]]
    208 '''Contributors:''' sdegrande
     229'''Contributors:'''