Changes between Version 14 and Version 15 of OdtExportPlugin


Ignore:
Timestamp:
Mar 11, 2015, 1:39:13 PM (8 years ago)
Author:
figaro
Comment:

Cosmetic changes, tagged with license. Note: license incorrectly added to code.

Legend:

Unmodified
Added
Removed
Modified
  • OdtExportPlugin

    v14 v15  
    11[[PageOutline(2-5,Contents,pullout)]]
    2 = Export wiki pages as OpenDocument (ODT) =
    32
    4 == Description ==
     3= Export wiki pages as OpenDocument (ODT)
     4
     5== Description
    56
    67This plugins can convert a wiki page to an [http://en.wikipedia.org/wiki/Opendocument OpenDocument] Text file (ODT).
    78
    8 The file can be opened with any compatible office suite, such as !OpenOffice, KOffice, IBM Symphony, etc. Currently, it's only been tested with !OpenOffice.
     9The file can be opened with any compatible office suite, such as !OpenOffice, KOffice, IBM Symphony, etc. Currently, it has only been tested with !OpenOffice.
    910
    1011The XSLT stylesheets come from the [http://xhtml2odt.org XHTML2ODT] project.
    1112
    12 
    13 == Installation ==
    14 
    15 This plugin was tested with Trac version 0.11. Please ensure the following python modules are installed before installing this plugin:
    16 
    17  * [http://pypi.python.org/pypi/uTidylib python-uTidyLib]
    18  * [http://pypi.python.org/pypi/lxml python-lxml]
    19  * [http://pypi.python.org/pypi/PIL python-PIL] (sometimes named python-imaging)
    20 
    21 Refer to the [trac:TracPlugins Trac plugin documentation] for details on how to build and install plugins and macros. You will probably have to enable the plugin by editing the `components` section of your `trac.ini`, for example:
    22 {{{
    23 #!ini
    24 [components]
    25 odtexport.* = enabled
    26 }}}
    27 
    28 After installing, a new alternative format should appear on the bottom of each wiki page, next to the "Plain Text" link.
    29 
    30 == Options ==
    31 
    32 In `trac.ini`, you can setup a few options :
    33  * '''get_remote_images''' (boolean, defaults to `true`) : whether the plugin should download the remote images
    34  * '''replace_keyword''' (string, defaults to `TRAC-ODT-INSERT`) : the string in the ODT template file to replace with the wiki page content. This keyword ''must'' be unstyled and alone on its own line. If not present, the wiki content will be appended to the template.
    35  * '''cut_start_keyword''' (string, defaults to `TRAC-ODT-CUT-START`) and '''cut_stop_keyword''' (string, defaults to `TRAC-ODT-CUT-STOP`) : the text between these strings in the ODT template will be removed. See note below for the reason for these tags.
    36  * '''dpi''' (integer, defaults to `96`) : the screen DPI.
    37  * '''img_default_width''' (string, defaults to `8cm`) : the width of an exported image when the plugin can't compute it.
    38  * '''img_default_height''' (string, defaults to `6cm`) : the height of an exported image when the plugin can't compute it.
    39  * '''remove_macros''' (list, defaults to `PageOutline, TracGuideToc, TOC`) : the macros which will be removed on export. This is mainly because the table of contents should be handled in the ODT directly, not by generating a list of links. Warning, if these macros are in a sub-page included by the IncludeMacro (or similar), they will not be removed.  In the specific case of IncludeMacro however, there is a [ticket:9035 patch available] to fix that.
    40 
    41 Those options must be put under a `[odtexport]` section in the ini file, such as :
    42 {{{
    43 #!ini
    44 [odtexport]
    45 get_remote_images = False
    46 replace_keyword = REPLACE_ME
    47 }}}
    48 
    49 === About the `TRAC-ODT-CUT-START` and `TRAC-ODT-CUT-STOP` tags ===
    50 
    51 In an ODT file, the only styles that will be saved are the styles which are applied to some content in the document. If you want to create an empty ODT document for this plugin, and still want to define styles which will be applied to the wiki content, you have to write some dummy text, apply the styles to this text, and surround the text in the `TRAC-ODT-CUT-START` and `TRAC-ODT-CUT-STOP` tags. This way, the styles will be retained in the ODT file, but the dummy text will be removed on export.
    52 
    53 === Choosing a template ===
    54 
    55 The default template is named `wikipage.odt`. You can use a custom template by creating a file with this name and putting it in the `templates` directory of your Trac instance. This template will be used by default for all the pages.
    56 
    57 You can also create other ODT files to be used as templates, and put them in the same directory. Then, you can use a special macro in the wiki page to choose the template. This macro is `OdtTemplate` and can be used as such: `[[OdtTemplate(my_other_template)]]`. The `.odt` suffix will be appended, don't put it in the macro.
    58 
    59 Finally, you can simply attach the template to the page, and use the `OdtTemplate` macro to select it.
    60 
    61 The order of preference when looking for the template file is:
    62  1. in the page's attachments
    63  2. in the Trac instance's `templates` directory
    64  3. in the OdtExportPlugin's `templates` directory
    65 
    66 The first found is used.
    67 
    68 == Bugs/Feature Requests ==
     13== Bugs/Feature Requests
    6914
    7015Existing bugs and feature requests for OdtExportPlugin are
     
    7419[http://trac-hacks.org/newticket?component=OdtExportPlugin&owner=abompard new ticket].
    7520
    76 == Download ==
     21[[TicketQuery(component=OdtExportPlugin&group=type,format=progress)]]
     22
     23== Download
    7724
    7825{{{
     
    8633Download the zipped source from [download:odtexportplugin here].
    8734
    88 == Source ==
     35== Source
    8936
    9037You can check out OdtExportPlugin from [http://trac-hacks.org/svn/odtexportplugin here] using Subversion, or [source:odtexportplugin browse the source] with Trac.
    9138
    92 == Example ==
     39== Installation
     40
     41This plugin was tested with Trac version 0.11. Please ensure the following python modules are installed before installing this plugin:
     42
     43 * [pypi:uTidylib python-uTidyLib]
     44 * [pypi:lxml python-lxml]
     45 * [pypi:PIL python-PIL], also known as python-imaging
     46
     47Refer to the [trac:TracPlugins Trac plugin documentation] for details on how to build and install plugins and macros. You will probably have to enable the plugin by editing the `components` section of your `trac.ini`:
     48{{{
     49#!ini
     50[components]
     51odtexport.* = enabled
     52}}}
     53
     54After installing, a new alternative format should appear on the bottom of each wiki page, next to the "Plain Text" link.
     55
     56== Configuration
     57
     58In `trac.ini`, you can set a few options :
     59 * '''get_remote_images''' (boolean, defaults to `true`) : whether the plugin should download the remote images
     60 * '''replace_keyword''' (string, defaults to `TRAC-ODT-INSERT`) : the string in the ODT template file to replace with the wiki page content. This keyword ''must'' be unstyled and alone on its own line. If not present, the wiki content will be appended to the template.
     61 * '''cut_start_keyword''' (string, defaults to `TRAC-ODT-CUT-START`) and '''cut_stop_keyword''' (string, defaults to `TRAC-ODT-CUT-STOP`) : the text between these strings in the ODT template will be removed. See note below for the reason for these tags.
     62 * '''dpi''' (integer, defaults to `96`) : the screen DPI.
     63 * '''img_default_width''' (string, defaults to `8cm`) : the width of an exported image when the plugin can't compute it.
     64 * '''img_default_height''' (string, defaults to `6cm`) : the height of an exported image when the plugin can't compute it.
     65 * '''remove_macros''' (list, defaults to `PageOutline, TracGuideToc, TOC`) : the macros which will be removed on export. This is mainly because the table of contents should be handled in the ODT directly, not by generating a list of links. Warning, if these macros are in a sub-page included by the IncludeMacro (or similar), they will not be removed.  In the specific case of IncludeMacro however, there is a [ticket:9035 patch available] to fix that.
     66
     67Those options must be placed under a `[odtexport]` section in the `trac.ini` file:
     68{{{
     69#!ini
     70[odtexport]
     71get_remote_images = False
     72replace_keyword = REPLACE_ME
     73}}}
     74
     75=== About the `TRAC-ODT-CUT-START` and `TRAC-ODT-CUT-STOP` tags
     76
     77In an ODT file, the only styles that will be saved are the styles which are applied to some content in the document. If you want to create an empty ODT document for this plugin, and still want to define styles which will be applied to the wiki content, you have to write some dummy text, apply the styles to this text, and surround the text in the `TRAC-ODT-CUT-START` and `TRAC-ODT-CUT-STOP` tags. This way, the styles will be retained in the ODT file, but the dummy text will be removed on export.
     78
     79=== Choosing a template
     80
     81The default template is named `wikipage.odt`. You can use a custom template by creating a file with this name and putting it in the `templates` directory of your Trac instance. This template will be used by default for all the pages.
     82
     83You can also create other ODT files to be used as templates, and put them in the same directory. Then, you can use a special macro in the wiki page to choose the template. This macro is `OdtTemplate` and can be used as such: `[[OdtTemplate(my_other_template)]]`. The `.odt` suffix will be appended, don't put it in the macro.
     84
     85Finally, you can simply attach the template to the page, and use the `OdtTemplate` macro to select it.
     86
     87The order of preference when looking for the template file is:
     88 1. in the page's attachments
     89 1. in the Trac instance's `templates` directory
     90 1. in the OdtExportPlugin's `templates` directory
     91
     92The first preference that is found is used.
     93
     94== Example
    9395
    9496Once installed, a new entry shows up below the ''Download in other formats'' section at the end of the page. Click and save to disk, and open with a compatible office suite such as !OpenOffice.
    9597
    96 == Recent Changes ==
     98== Recent Changes
    9799
    98100[[ChangeLog(odtexportplugin, 3)]]
    99101
    100 == Author/Contributors ==
     102== Author/Contributors
    101103
    102104'''Author:''' [wiki:abompard Aurélien Bompard] [[BR]]
    103 '''Maintainer:''' [wiki:abompard Aurélien Bompard] [[BR]]
     105'''Maintainer:''' [[Maintainer]] [[BR]]
    104106'''Contributors:'''