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