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