packages/emacs-24.1/org-odt-readme.txt

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