de21d3687e1e3749dd67ed7d9414b0d38a2a8aed
[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. If you had already been using the new exporter from contrib, you should
149    remove the following lines from your local.mk:
150    : ORG_ADD_CONTRIB = org-e-*
151
152 2. Next, issue =make clean= before =git pull=.
153
154 2. Export engine renamed from =org-export= to =ox=
155
156 3. Backend requires renamed =org-e-*= to =ox-*=
157
158 4. All backend specific variables and functions renamed:
159    - =org-export-*= to =org-*= (e.g. org-html-xml-declaration, ..)
160    - =org-e-*= to =org-*= (e.g. org-latex-classes, org-ascii-bullets, ..)
161
162 5. Generic export variables retain the name =org-export-*=,
163    (e.g. org-export-dispatch-use-expert-ui,
164    org-export-filter-headline-functions, ..)
165
166 6. =org-latex-to-pdf-process= renamed =org-latex-pdf-process=
167
168 7. This is a guess, export snippets and backend symbols renamed:
169    - =e-<backend>= to =<backend>=
170
171 Again, please refer to [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge for more details.
172
173
174 * New global keywords
175   
176 ** New #+TOC keyword
177
178 In the exporting of a table of contents, options only allowed for setting the
179 level of the deepest table of contents headline, like so:
180
181 #+begin_src org
182   ,#+OPTIONS: TOC:2
183 #+end_src
184
185 Upon export, only first and second level headlines would be included in the generated
186 table of contents. With the new exporter, a dedicated =#+TOC= now exists which allows for
187 futher customization: adding table of contents, lists of tables, and lists of listings at
188 specific locations during export. 
189
190 #+BEGIN_SRC org
191   ,#+TOC: headlines 2
192   ,#+TOC: tables
193   ,#+TOC: listings
194 #+END_SRC
195
196 See the [[http://orgmode.org/manual/Table-of-contents.html][Table of contents]] section in the manual for more information.
197
198 * Syntax changes
199
200 ** Export snippets
201
202    Export snippets are a generalization of ~@<tag>~ concept, which has
203    been removed, and the inline version of ~#+begin_backend...#+end_backend~ blocks.
204
205    Their syntax is ~@@backend:value~ where ~backend~ is the targetted
206    export backend (e.g. ~html~) and ~value~ can contain anything but
207    ~@@~.
208
209    When export is done with ~backend~, the snippet is replaced with
210    ~value~, otherwise it is removed.  Whitespace characters around
211    the construct are never deleted.
212
213 ** Footnote definitions
214
215    A footnote definition (not inline) can now be ended with two
216    consecutive blank lines.
217
218    As a consequence, multiple paragraphs inside can be written
219    normally, separated with blank lines, instead of relying on the
220    ~\par~ command.
221
222 ** Org-mode per-file options
223
224 - The =#+STYLE= option is now specified with =#+HTML_HEAD=
225
226 - Using =#+SETUPFILE: file= versus =#+INCLUDE: "file".=
227
228    =#+INCLUDE:= keyword requires quotes around the file name. Those
229   are optional in =#+SETUPFILE:=.
230
231   There is now also a clear difference between these two statements.
232   The first will only read keyword statements like =#+TODO:= and use
233   this to set up the current file. The second will pull in the entire
234   content of the file during export. The =#+INCLUDE:= statement will
235   make every headline in the included file will be a child of the
236   headline containing the include keyword. You can overwrite this
237   behaviour with =:minlevel= num parameter.
238
239 - Attribute lines now take plists (similar to [[http://orgmode.org/worg/org-contrib/babel/][Babel code block syntax]]):
240
241    : #+attr_latex :width 5cm
242    : #+attr_beamer :options width=5cm
243    : #+attr_html: :width 200px
244
245   *TIP:* To upgrade from old =attr_html= lines with verbatim HTML
246   attribute syntax, you could try a Perl one-liner like the following,
247   replacing =filename.org= with your file (or a bunch of files with
248   =*.org= if you're feeling adventurous -- no warranty, make sure
249   you're backed up first!).
250   
251    : perl -i.bak -pe "s/([a-z]+)=(\"|')(.*?)\2/:\1 \3/g if /^#\+attr_html/i" filename.org
252
253 - Beamer backend now interprets nested headline levels as blocks instead
254   of lists.  For more guidance, see [[file:exporters/beamer/ox-beamer.org][this page]].
255