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