org-8.0.org

   1 #+TITLE: Upgrading to Org 8.0 or the current master branch
   2 #+AUTHOR: Bastien Guerry
   3 #+EMAIL: bzg @ gnu DOT org
   4 #+LANGUAGE:  en
   5 #+OPTIONS: toc:t
   6 #+html_head: <link rel="stylesheet" title="Standard" href="./style/worg.css" type="text/css" />
   7
   8 # This file is released by its authors and contributors under the GNU
   9 # Free Documentation license v1.3 or later, code examples are released
  10 # under the GNU General Public License v3 or later.
  11
  12 * Introduction
  13
  14 #+INDEX: 8.0
  15 #+INDEX: exporter
  16 #+INDEX: migrating
  17
  18 The release of Org-mode 8.0 (and the git repository master branch, as
  19 of [[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=1cac3127c2f810e83fcc1203f1dd2b15250a687e][commit 1cac3127c]]) uses a new export framework, developed by Nicolas
  20 Goaziou. This document provides information on general changes to Org,
  21 as well as the steps needed to update your configuration properly.
  22
  23 If the instructions below do not help solving your problem, please ask
  24 any question on the [[https://orgmode.org/community.html][mailing list]]. Keep in mind that the new export
  25 framework is under heavy development, and posting to the mailing list
  26 will help not only to resolve your issues, but also make sure that
  27 documentation is properly udpated for the benefit of others with
  28 similar issues.
  29
  30 This page serves as an upgrade guide for the changes widely affecting
  31 users. /Please/ refer to the [[file:exporters/ox-overview.org][new exporter overview]], which contains an up
  32 to date list of Org-mode exporters, and links to backend-specific
  33 setup and usage details.
  34
  35 * Files moved to =contrib/=
  36
  37 These files have been moved to the =contrib/= directory.
  38
  39 - =org-colview-xemacs.el=
  40 - =org-mew.el=
  41 - =org-wl.el=
  42 - =org-w3m.el=
  43 - =org-vm.el=
  44 - =ox-taskjuggler.el= (was org-taskjuggler.el)
  45 - =ox-freemind.el= (was org-freemind.el)
  46
  47 If you were using them, you need to [[https://orgmode.org/manual/Installation.html][add the =contrib/lisp= directory]]
  48 of the Org distribution to the Emacs =load-path=.
  49
  50
  51 * Original announcement of the new exporter
  52
  53 The most comprehensive overview of the new exporter may be found in Nicolas' merge
  54 announcement [[https://list.orgmode.org/876229nrxf.fsf@gmail.com][in this email]] to the mailing list. Please scan the post, as you may find
  55 answers to your questions there.
  56
  57 * Updating global export configuration options
  58
  59 Global export options start with the =org-export-*= prefix, most of them
  60 are in the =ox.el= file.
  61
  62 Most generic export options should not require any changes. If
  63 you find that a generic option is useless or broken or badly documented in
  64 the manual, please report it to the list.
  65
  66 * Backend-specific configuration options
  67
  68 Backend-specific options are now defined via the convention =ox-backend-*=. For example:
  69
  70 - =org-html-*= for =HTML= and live in =ox-html.el=
  71 - =org-latex-*= for =LaTeX= and live in =ox-latex.el=
  72 - Etc.
  73
  74 There is a new variable =org-export-backends= which controls what backends
  75 are loaded when you lauch Org.  By default, the =ASCII=, =HTML= and =LaTeX=
  76 are loaded; in contrast with the old exporter behavior, others will need to be explicitly
  77 loaded in order to use them. See the [[Upgrading your setup][upgrade]] section for instructions.
  78
  79 ** HTML-specific changes
  80
  81 Some html-specific options were renamed more signficantly or deleted. Examine this
  82 table and update accordingly:
  83
  84 | Org 7.9.3f (maint)                     | Master (8.0)                           |
  85 |----------------------------------------+----------------------------------------|
  86 | org-export-html-style                  | org-html-head                          |
  87 | org-export-html-style-extra            | org-html-head-extra                    |
  88 | org-export-html-style-default          | org-html-head-include-default-style    |
  89 | org-export-html-style-include-scripts  | org-html-head-include-scripts          |
  90 | org-export-htmlized-org-css-url        | org-org-htmlized-css-url (in ox-org.el |
  91 |----------------------------------------+----------------------------------------|
  92 | org-export-html-headline-anchor-format | Deleted                                |
  93 | org-export-html-date-format-string     | Deleted                                |
  94 | org-export-html-content-div            | Deleted                                |
  95 | org-export-html-html-helper-timestamp  | Deleted                                |
  96
  97 ** Org publishing specific changes
  98 Some changes also specifically affect =org-publish-project-alist= settings. The publishing
  99 functions are not loaded until the corresponding backend has been loaded.  You need to
 100 update =org-publish-project-alist= and to use the function from the new publishing engine
 101 in the table below:
 102
 103 | Old publishing engine    | New publishing engine      |
 104 |--------------------------+----------------------------|
 105 | org-publish-org-to-html  | org-html-publish-to-html   |
 106 | org-publish-org-to-org   | org-org-publish-to-org     |
 107 | org-publish-org-to-latex | org-latex-publish-to-latex |
 108 | ...                      | ...                        |
 109
 110
 111 To specify a style for the project =:style= keyword changes to =:html-head=
 112
 113 If something does not work, please report it on the mailing list.
 114
 115
 116
 117 * Upgrading your setup
 118
 119 The practical implication for users upgrading from Org-mode < version 7.9.4f is two-fold:
 120
 121 - You must search your configuration for the existence of varaibles starting with
 122   =org-export-= and change their names (e.g. =org-export-html-validation-link= is now
 123   =org-html-validation-link=). /See sections below changes specific to the HTML and
 124   Publishing backends/.
 125
 126 - If you use exporters in addition to =ASCII=, =HTML=, and/or =LaTeX=, you need to load them
 127   explicitly in your config via one of two ways (refer to  [[https://list.orgmode.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]], section
 128   3 on Installation, for explanation of the two methods):
 129
 130 *1: Load exporter upon first export execution per session*
 131 #+begin_example
 132 setq org-export-backends (quote (
 133        beamer
 134        md
 135        ...
 136        taskjuggler)))
 137 #+end_example
 138
 139 *2: Loading all listed exporters upon Emacs startup*
 140 #+begin_example
 141 (require 'ox-beamer)
 142 (require 'ox-md)
 143 ...
 144 (require 'ox-taskjuggler)
 145 #+end_example
 146
 147 *Note:* Please stick to /one/ of the above two methods!
 148
 149 ** Using Org 7.9.3f or earlier versions of Org
 150
 151 For users who used the new exporter prior to its integration into the current master
 152 branch, here are some additional steps you may need to do in order to upgrade properly:
 153
 154 1. Issue =make clean= before =git pull= and any changes to your
 155    configuration.
 156
 157 2. If you had already been using the new exporter from contrib, you should
 158    remove the following lines from your local.mk:
 159    : ORG_ADD_CONTRIB = org-e-*
 160
 161 3. Export engine renamed from =org-export= to =ox=
 162
 163 4. Backend requires renamed =org-e-*= to =ox-*=
 164
 165 5. All backend specific variables and functions renamed:
 166    - =org-export-*= to =org-*= (e.g. org-html-xml-declaration, ..)
 167    - =org-e-*= to =org-*= (e.g. org-latex-classes, org-ascii-bullets, ..)
 168
 169 6. Generic export variables retain the name =org-export-*=,
 170    (e.g. org-export-dispatch-use-expert-ui,
 171    org-export-filter-headline-functions, ..)
 172
 173 7. =org-latex-to-pdf-process= renamed =org-latex-pdf-process=
 174
 175 8. This is a guess, export snippets and backend symbols renamed:
 176    - =e-<backend>= to =<backend>=
 177
 178 Again, please refer to [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge for more details.
 179
 180
 181 * New global keywords
 182
 183 ** New #+TOC keyword
 184
 185 In the exporting of a table of contents, options only allowed for setting the
 186 level of the deepest table of contents headline, like so:
 187
 188 #+begin_src org
 189   ,#+OPTIONS: TOC:2
 190 #+end_src
 191
 192 Upon export, only first and second level headlines would be included in the generated
 193 table of contents. With the new exporter, a dedicated =#+TOC= now exists which allows for
 194 futher customization: adding table of contents, lists of tables, and lists of listings at
 195 specific locations during export.
 196
 197 #+BEGIN_SRC org
 198   ,#+TOC: headlines 2
 199   ,#+TOC: tables
 200   ,#+TOC: listings
 201 #+END_SRC
 202
 203 See the [[https://orgmode.org/manual/Table-of-contents.html][Table of contents]] section in the manual for more information.
 204
 205 * Syntax changes
 206
 207 ** Export snippets
 208
 209    Export snippets are a generalization of ~@<tag>~ concept, which has
 210    been removed, and the inline version of ~#+begin_backend...#+end_backend~ blocks.
 211
 212    Their syntax is ~@@backend:value~ where ~backend~ is the targetted
 213    export backend (e.g. ~html~) and ~value~ can contain anything but
 214    ~@@~.
 215
 216    When export is done with ~backend~, the snippet is replaced with
 217    ~value~, otherwise it is removed.  Whitespace characters around
 218    the construct are never deleted.
 219
 220 ** Footnote definitions
 221
 222    A footnote definition (not inline) can now be ended with two
 223    consecutive blank lines.
 224
 225    As a consequence, multiple paragraphs inside can be written
 226    normally, separated with blank lines, instead of relying on the
 227    ~\par~ command.
 228
 229 ** Org-mode per-file options
 230
 231 - The =#+STYLE= option is now specified with =#+HTML_HEAD=
 232
 233 - Using =#+SETUPFILE: file= versus =#+INCLUDE: "file".=
 234
 235    =#+INCLUDE:= keyword requires quotes around the file name. Those
 236   are optional in =#+SETUPFILE:=.
 237
 238   There is now also a clear difference between these two statements.
 239   The first will only read keyword statements like =#+TODO:= and use
 240   this to set up the current file. The second will pull in the entire
 241   content of the file during export. The =#+INCLUDE:= statement will
 242   make every headline in the included file will be a child of the
 243   headline containing the include keyword. You can overwrite this
 244   behaviour with =:minlevel= num parameter.
 245
 246 - Attribute lines now take plists (similar to [[https://orgmode.org/worg/org-contrib/babel/][Babel code block syntax]]):
 247
 248    : #+attr_latex: :width 5cm
 249    : #+attr_beamer: :options width=5cm
 250    : #+attr_html: :width 200px
 251
 252   *TIP:* To upgrade from old =attr_html= lines with verbatim HTML
 253   attribute syntax, you could try a Perl one-liner like the following,
 254   replacing =filename.org= with your file (or a bunch of files with
 255   =*.org= if you're feeling adventurous -- no warranty, make sure
 256   you're backed up first!).
 257
 258    : perl -i.bak -pe "s/([a-z]+)=(\"|')(.*?)\2/:\1 \3/g if /^#\+attr_html/i" filename.org
 259
 260 - Beamer backend now interprets nested headline levels as blocks instead
 261   of lists.  For more guidance, see [[file:exporters/beamer/ox-beamer.org][this page]].
 262