Changes between Version 38 and Version 39 of TracWikiPrintPlugin


Ignore:
Timestamp:
Feb 8, 2013, 4:39:55 AM (11 years ago)
Author:
anonymous
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracWikiPrintPlugin

    v38 v39  
    1010 * Customizable front page for PDF book format
    1111 * Automatic creation of Table of Contents if ![[PageOutline]] or ![[TOC]] Macro is used
    12 
    13 The style of the resulting PDF or HTML can be fully customized using CSS files.
     12 * The style of the resulting PDF or HTML can be fully customized using CSS files.
    1413
    1514== News ==
     15 * '''2013-02-07: Wiki'''. Cleaned up page and added more useful information.
    1616 * '''2011-09-26: Version 1.9.2'''. New option ''omit_macros'' to specify a list of macros to be removed on PDF.
    1717 * '''2011-09-23: Version 1.9.1'''. Included ''omit_links'' and ''rebase_links'' options in .ini section.
     
    2323 * '''2008-04-07: Version 1.1'''. Fix problems with images and attachments with no !wiki:PageName, now it should work.
    2424
    25 == Usage instructions ==
     25== Install ==
    2626There are several '''dependencies''':
    2727
     
    3535To install dependencies (PIL/!!ReportLab/HTML5Lib/Pygments/pyPDF):
    3636
    37  * Debian:
     37 * On Debian/Ubuntu:
    3838   * `aptitude install python-imaging python-reportlab python-html5lib python-pygments python-pypdf`
    39  * Fedora:
     39 * On Fedora/Redhat:
    4040   * `yum install  python-imaging python-reportlab python-html5lib python-pygments pyPdf`
    4141
     
    5151wikiprint.* = enabled
    5252}}}
    53 When 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:
     53After 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:
    5454
    5555 * PDF Article
     
    5757 * Printable HTML
    5858
    59 If you're behind a proxy, add something like this to your .wsgi file so '''remote''' resources can be downloaded when creating pdfs:
     59== Settings ==
     60If you're behind a '''proxy''', add something like this to your .wsgi file so '''remote''' resources can be downloaded when creating pdfs:
    6061
    6162{{{
     
    6465os.environ['no_proxy'] = '.company.com'
    6566}}}
     67If 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`):
    6668
    67 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`):
    6869{{{
    6970...
     
    7677...
    7778}}}
    78 
    79 Additional options can be set by creating a ''wikiprint'' section in ''trac.ini'':
     79Additional 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):
    8080
    8181{{{
    8282[wikiprint]
    8383toc_title = Table of Contents
    84 #CSS and content files (or URLS, using http://...)
    85 css_url = c:/path/to/file.css
    86 article_css_url = c:/path/to/article.css
    87 book_css_url = c:/path/to/book.css
    88 frontpage_url = c:/path/to/frontpage.html
    89 extracontent_url = c:/path/to/extracontent.html
    90 rebase_links = http://anotherserver.com/path
    91 omit_links = False
    92 
     84css_url = /path/to/file.css
     85article_css_url = /path/to/article.css
     86book_css_url = /path/to/book.css
     87frontpage_url = /path/to/frontpage.html
     88extracontent_url = /path/to/extracontent.html
    9389httpauth_user = wikiprint_user
    9490httpauth_password = *password*
     91
     92rebase_links = http://anotherserver.com/path
     93omit_links = false
    9594}}}
    9695Most of these options can be also set from the web administrative interface:
     
    9897[[Image(wiki:TracWikiPrintPlugin:admin_options.jpg, 60%, border=1)]]
    9998
    100 Not available in administrative interface yet:
     99=== Customizing styles ===
     100!WikiPrint allows customization of documents by three different options:
    101101
    102  * '''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).
    103  * '''omit_links''': Remove internal wiki links from generated PDFs.
    104  * '''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).
     102 * '''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.
     103 * '''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.
     104 * '''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.
    105105
    106 === Some notes ===
    107 ==== xhtml2pdf special tags and styles ====
    108 !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].
     106For more information about the styles that affect the PDF output, see the [attachment:"pisa-en.pdf" xhtml2pdf  manual].
    109107
    110 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.
     108=== Customizing front page, header, footer, contents ===
     109 * '''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''
     110 * '''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.
    111111
    112 ==== Images and links ====
    113 !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.
    114 
    115 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).
    116 
    117 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.
    118 
    119 '''Authentication and permissions'''
    120 
    121 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'''.
     112=== Authentication ===
     113When 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'''.
    122114
    123115Optionally, is HTTP Basic or Digest authentication is used, wikiprint can be configured to log in using '''httpauth_user''' and '''httpauth_password''' options.
    124116
    125 === Security Concerns ===
     117=== Not available in administrative interface yet: ===
     118 * '''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).
     119 * '''omit_links''': Remove internal wiki links from generated PDFs.
     120 * '''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).
     121
     122== Permissions ==
    126123Wikiprint defines three new permissions:
    127124
    128125 * WIKIPRINT_ADMIN: Allow users to acces the ''Wikiprint Options'' admin page, and configure wikiprint options.
    129126 * WIKIPRINT_BOOK: Allow users to access the ''Make Book'' admin page.
    130  * 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.
     127 * 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.
    131128
    132 === Export formats ===
     129== Exporting and formats ==
    133130!WikiPrint adds several download formats to the bottom of the wiki page. Following is the description of the available formats.
    134131
    135 ==== PDF Article ====
     132=== PDF Article ===
    136133PDF 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.
    137134
     
    140137PDF article can be used to combine several wiki pages too, from the administrative interface.
    141138
    142 ==== PDF Book ====
    143 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.
     139=== PDF Book ===
     140This 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.
    144141
    145142This is specially useful for combining several wiki pages from the administrative interface:
     
    147144[[Image(wiki:TracWikiPrintPlugin:admin_makebook.jpg, 60%, border=1)]]
    148145
    149 ==== Printable HTML ====
    150 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.
     146=== Printable HTML ===
     147This 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.
    151148
    152149=== Combining pages ===
    153 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.
     150When 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.
    154151
    155152You can specify a Title, Subject, Date and Version for the exported document.
    156153
    157154=== Tag replacement ===
    158 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.
     155When 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.
    159156
    160157The following tags are supported:
     
    165162 * #VERSION: Replaced with the ''Version'' field when combining pages from the administrative interface, or the current page version when exporting from the wiki.
    166163
    167 === Customizing styles ===
    168 !WikiPrint allows customization of documents by three different options:
     164== Notes ==
     165=== xhtml2pdf special tags and styles ===
     166!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].
    169167
    170  * '''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.
    171  * '''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.
    172  * '''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.
     168Also, 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.
    173169
    174 For more information about the styles that affect the PDF output, see the [attachment:"pisa-en.pdf" xhtml2pdf  manual].
     170=== Images and links ===
     171!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.
    175172
    176 === Customizing front page, header, footer, contents ===
    177  * '''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''
    178  * '''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.
     173In order to generate the PDF, ''xhtml2pdf'' library will try to download the images from their absolute URL (exactly as your web browser would do).
     174
     175For 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.
    179176
    180177== Bugs/Feature Requests ==
     
    191188== Patches ==
    192189=== Windows & IIS ===
    193 If you should need to access the ressources 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.
     190If 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.
    194191
    195192== Recent Changes ==
     
    197194
    198195== Author/Contributors ==
    199 '''Author:''' [wiki:airadier] [[BR]] '''Maintainer:''' [wiki:airadier] [[BR]] '''Contributors:'''
     196'''Author:''' [wiki:airadier] [[BR]] '''Maintainer:''' [wiki:airadier] [[BR]] '''Contributors:''' (always welcome!)