doc/ReleaseNotes.org

   1 #+TITLE:        OpenDocumentText Exporter for Orgmode
   2 #+AUTHOR:       Jambunathan K
   3 #+EMAIL:        emacs-orgmode@gnu.org
   4 #+DATE:         %Y-%m-%d %T %Z
   5 #+DESCRIPTION:
   6 #+KEYWORDS:
   7 #+LANGUAGE:  en
   8 #+OPTIONS:   H:3 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
   9 #+OPTIONS:   TeX:t LaTeX:dvipng skip:nil d:nil todo:t pri:nil tags:not-in-toc
  10
  11 #+EXPORT_SELECT_TAGS: export
  12 #+EXPORT_EXCLUDE_TAGS: noexport
  13 #+LINK_UP:
  14 #+LINK_HOME:
  15 #+XSLT:
  16
  17
  18 * Summary
  19
  20   This package adds support for exporting of Orgmode files to
  21   OpenDocumentText.
  22
  23   The latest version of this document is available at
  24
  25 # - Text version :: http://repo.or.cz/w/org-mode/org-jambu.git/blob_plain/HEAD:/doc/ReleaseNotes.org
  26   - Web page :: http://repo.or.cz/w/org-mode/org-jambu.git/blob_plain/HEAD:/packages/README.html
  27
  28 * Compatibility with Official Orgmode
  29   :PROPERTIES:
  30   :CUSTOM_ID: compatibility
  31   :END:
  32
  33   This release is is as good as *org-20110613 (git commit c4737ae)*
  34   with *only* the following changes left out.
  35
  36   | git commit | Description                                                            |
  37   |------------+------------------------------------------------------------------------|
  38   | 2f50b1     | add an alternate for inline images                                     |
  39   | 49e6bc     | Fix for html & docbook export of desc list items                       |
  40   | a201b1     | Fix HTML export of footnotes with lists, tables, quotes.               |
  41   | 9f57b8     | Mixed export of numbered and unnumbered sections in HTML               |
  42   | 438536     | Revert "Change underscores to hyphens in section labels"               |
  43   | 33bae1     | Revert "Fix markup problems when using references in source fragments" |
  44   | fa12fe     | Revert "org-html.el: Fix export of table.el tables."                   |
  45   | f72541     | Revert "HTML export -- Allow to change the name of the global DIV"     |
  46
  47 * Implementation Details
  48
  49   This package enhances Orgmode in the following manner:
  50   1. A new line-oriented generic exporter
  51   2. All new html exporter re-implemented as a plugin to (1).
  52   3. A odt backend as a plugin to (1).
  53
  54   Feature (1) is provided by =org-lparse.el=.
  55   Feture (2) is provided by =lisp/org-html.el=.
  56   Feature (3) is provided by =lisp/org-odt.el=.
  57
  58   The new html exporter is feature-compatible with the official html
  59   exporter.
  60
  61 * Notes for Reviewers and Fellow Developers
  62
  63   =org-lparse= is the entry point for the generic exporter and
  64   drives html and odt backends.
  65
  66   =org-do-lparse= is the genericized version of the original
  67   =org-export-as-html= routine.
  68
  69   =C-h v org-lparse-native-backends= is a good starting point for
  70   exploring the generic exporter.
  71
  72 * Package Layout
  73
  74   - lisp/org-html.el :: Generic driver and the HTML exporter. The
  75        generic driver uses =org-parse= as prefix.
  76   - lisp/org-odt.el :: The OpenDocumentText backend
  77   - contrib/odt/BasicODConverter-0.8.0.oxt :: OpenOffice extension for
  78        converting between various file formats supported by
  79        OpenOffice. A poor clone of unoconv.
  80   - contrib/odt/BasicODConverter/Filters.bas ::
  81   - contrib/odt/BasicODConverter/Main.bas :: Basic files that
  82        contribute to the above extension.
  83   - contrib/odt/OpenDocument-schema-v1.1.rnc :: rnc files for above
  84        rng files. Generated using [[http://www.thaiopensource.com/relaxng/trang.html][trang]].
  85   - contrib/odt/OpenDocument-schema-v1.1.rng :: Copy of
  86        http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-schema-v1.1.rng
  87
  88   - contrib/odt/OpenDocument-v1.2-cs01-schema.rng :: Copy of
  89        http://docs.oasis-open.org/office/v1.2/cs01/OpenDocument-v1.2-cs01-schema.rng
  90   - contrib/odt/OpenDocument-v1.2-cs01-manifest-schema.rng :: Copy of
  91        http://docs.oasis-open.org/office/v1.2/cs01/OpenDocument-v1.2-cs01-manifest-schema.rng
  92   - contrib/odt/OpenDocument-v1.2-cs01-manifest-schema.rnc ::
  93   - contrib/odt/OpenDocument-v1.2-cs01-schema.rnc :: rnc files for
  94        above rng files. Generated using [[http://www.thaiopensource.com/relaxng/trang.html][trang]].
  95   - contrib/odt/schemas.xml :: schema location file for auto
  96        validating the generated XML files Refer =C-h f
  97        rng-set-schema-file-and-validate= FILENAME and =C-h f
  98        rng-what-schema=. Related Thread:
  99        http://lists.gnu.org/archive/html/emacs-devel/2011-03/msg00857.html
 100   - contrib/odt/OrgOdtAutomaticStyles.xml :: The default styles.xml
 101        file used by the OpenDocumentText exporter.
 102   - contrib/odt/OrgOdtStyles.xml :: Automatic styles inserted in to
 103        content.xml
 104   - contrib/odt/files/org-mode-unicorn.png ::
 105   - contrib/odt/files/test.org :: Sample files for validating the
 106        exporter
 107   - contrib/odt/setup.el :: Helper file for initialization.
 108
 109 * Obtaining OpenDocumentExporter
 110
 111   The OpenDocumentExporter could be downloaded by one of the following
 112   methods:
 113
 114 ** git checkout
 115    - Checkout URL ::  http://repo.or.cz/r/org-mode/org-jambu.git
 116    - Web URL :: http://repo.or.cz/w/org-mode/org-jambu.git/
 117
 118 ** Conventional tar
 119    - Download URL :: http://repo.or.cz/w/org-mode/org-jambu.git/snapshot/HEAD.tar.gz
 120
 121 ** ELPA Tarball
 122    - Archive URL :: http://repo.or.cz/w/org-mode/org-jambu.git/blob_plain/HEAD:/packages/
 123
 124    The tarball is distributed as an org-odt package (for example
 125    =org-odt-20110519.tar=).
 126
 127    You need to have an *Org build >= org-20110626* for the exporter to
 128    function properly.
 129
 130    The most hassle-free way to download and install org-odt is through
 131    ELPA.
 132
 133    More help on all the above methods are available at
 134    http://orgmode.org/worg/org-faq.html.
 135
 136 * Test driving the Exporter
 137
 138   Once the package is installed in to your load-path, use
 139   =C-u M-x org-odt-unit-test= to visit an example org file bundled
 140   with this package.
 141
 142   1. Use =C-c C-e O= to export the buffer to OpenDocumentText.
 143   2. Use =M-x org-lparse= or =M-x org-lparse-and-open= for
 144      exporting to MS doc format.
 145   3. Use =M-x org-export-convert= on a buffer visiting odt file.
 146
 147   Steps 2 and 3 require that a converter be installed on the
 148   system. See [[#converter][this FAQ entry]] for more information on this.
 149
 150   - Misc. Info :: This package re-implements HTML exporter as
 151                   well. You will see the following warning message
 152                   *"Exporting to HTML using org-lparse..."* while you
 153                   are exporting using new HTML exporter.
 154
 155   - Hint :: If you are using BasicODConverter, you can use steps 2 and
 156             3 for exporting an Org outline to presentation formats
 157             like OpenOffice Impress (odp) and Microsoft Powerpoint
 158             (ppt)
 159   - Know Issues :: If you have dvipng installed it is possible that
 160                    the exported odt file has embedded images
 161                    clobbered. This is *not* a bug in the exporter but
 162                    seems like a bug in the package installer. See
 163                    http://lists.gnu.org/archive/html/bug-gnu-emacs/2011-06/msg00445.html.
 164
 165 * Bug Reports and Feature Requests
 166
 167   Send in your bug report and feature requests to
 168   =emacs-orgmode@gnu.org= or to =kjambunathan at gmail dot com=.
 169
 170   Please search the Mailing List Archive -
 171   http://lists.gnu.org/archive/html/emacs-orgmode/ for =org-odt=
 172   before posting a question or a request either to me or the mailing
 173   list.
 174
 175   Posting to mailing list is preferable. It is possible that your post
 176   helps another user out there.
 177
 178 * Possible Feature Enhacmentes
 179
 180 ** TODO Support for fontification of babel blocks
 181    May require enhancements to htmlfontify or htmlize packages.
 182
 183 ** TODO Enhance table.el to support Odt format
 184
 185 ** TODO Add support for exporting to odp
 186
 187    Use OpenOffice's File->Send->{Outline to Presentation |
 188    AutoAbstract to Presentation}. Also see
 189
 190    http://wiki.services.openoffice.org/wiki/Documentation/OOoAuthors_User_Manual/Impress_Guide/Creating_slides_from_an_outline
 191
 192 ** TODO Support for generating MathML for LaTeX fragments
 193    See http://lists.gnu.org/archive/html/emacs-orgmode/2011-03/msg01755.html
 194
 195 * Frequently Asked Questions
 196
 197 ** What features does the OpenDocumentExporter support?
 198
 199    At the moment, the exporter supports the following most commonly
 200    used features of Org
 201
 202    - Various Character Styles
 203    - Various Paragraph Styles (including Source Blocks)
 204    - Embedded ODT
 205    - Embedded MathML
 206    - Numbered, Bulleted and Description lists
 207    - Embedding and Resizing of Images including embedding of LaTeX fragments
 208    - Fuzzy, Dedicated and Radio Targets and Links
 209    - Tables
 210    - Footnotes
 211    - Outline Numbering and Table Of Contents
 212    - Special markups for elements like TODOs, Timestamps and Tags
 213
 214    The exporter is quite usable and stable.
 215
 216 ** Is OpenDocumentExporter part of Orgmode or Emacs?
 217
 218    Not yet. I have expressed my willingness to merge this package in
 219    to official Orgmode and thus to Emacs. The current maintainer of
 220    Orgmode - =Bastien Guerry bzg at gnu.org= - has agreed to consider
 221    the package for integration. If you are interested in having this
 222    package merged with Orgmode send your requests to the maintainer.
 223
 224    For the sake of record, I am the sole author of the changes
 225    included in this package and I am consenting to have this work or
 226    derivative works make it's way into Emacs proper. My FSF copyright
 227    assignment number is #618390.
 228
 229 ** How does it compare with official Orgmode
 230    For information about the latest release see [[#compatibility][this.]] For general
 231    information refer
 232    http://lists.gnu.org/archive/html/emacs-orgmode/2011-05/msg00751.html.
 233
 234 ** How can I export via command line?
 235
 236    See the following post
 237    http://lists.gnu.org/archive/html/emacs-orgmode/2011-04/msg00952.html.
 238
 239 ** How can I export to doc or docx format?
 240    :PROPERTIES:
 241    :CUSTOM_ID: converter
 242    :END:
 243    Here are the steps.
 244
 245 *** Install the converter program.
 246
 247     There are numerous converters that are available: =unoconv=,
 248     =PyODConverter=, =JODConverter= etc etc.
 249
 250     org-odt is distributed with it's own converter
 251     =BasicODConverter=. It is /Basic/ not only because it is
 252     implemented in StarBasic but is a a very basic clone of unoconv.
 253
 254 **** BasicODConverter
 255      Install [[http://repo.or.cz/w/org-mode/org-jambu.git/blob/HEAD:/contrib/odt/BasicODConverter-0.8.0.oxt][BasicODConverter]] as a OpenOffice Extension.
 256
 257 **** unoconv
 258
 259      If you prefer using unoconv as the converter add the following
 260      snippet to your =.emacs=.
 261
 262 #+begin_src emacs-lisp
 263   ;; not tested with unoconv
 264   (require 'org-html)
 265   (setq org-export-convert-process '("unoconv" "-f" "%f" "-o" "%d" "%i"))
 266 #+end_src
 267
 268 *** Convert using new interactive functions
 269
 270 **** Export an Org buffer
 271      Use =M-x org-lparse= or =M-x org-lparse-and-open= and follow
 272      the prompts. Use TAB for completion if you are not already using
 273      ido.
 274
 275 ***** Additional Note
 276      1. If you are using BasicODConverter you can export an Org file
 277         to =odp= or =ppt= formats.
 278      2. You can convert csv files to xls format
 279      3. OpenOffice doesn't ship with mediawiki or docbook export
 280         filters by default. So make sure that these extensions are
 281         installed before trying out these converters.
 282
 283 **** Export an existing file
 284
 285      Use =M-x org-export-convert= to convert an existing file.
 286
 287
 288 ** How can I apply custom styles?
 289
 290    See this thread:
 291    http://lists.gnu.org/archive/html/emacs-orgmode/2011-03/msg01460.html