org-8.0: make clean should be done before any configuration changes
[worg.git] / 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 [[http://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 [[http://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 [[http://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 [[http://article.gmane.org/gmane.emacs.orgmode/65574][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  [[http://article.gmane.org/gmane.emacs.orgmode/65574][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 [[http://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 [[http://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