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