1e0056cc3e75e84a4f1a3141a9607d60acde3310
[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
7 * Using the current master branch
8
9 #+INDEX: 8.0
10 #+INDEX: exporter
11 #+INDEX: migrating
12
13 As of [[http://orgmode.org/cgit.cgi/org-mode.git/commit/?id%3D1cac3127c2f810e83fcc1203f1dd2b15250a687e][commit 1cac3127c]], the master branch of Org's git repository uses the
14 new exporter by default.  If you use the master branch, you need to update
15 your configuration and change some syntactic elements of your Org files.
16
17 If the instructions below do not help solving your problem, please ask any
18 question on the mailing list, it will help us moving forward with
19 documenting everything for Org 8.0.
20
21 * Files moved to =contrib/=
22
23 These files have been moved to the =contrib/= directory.
24
25 If you were using them, you need to add the =contrib/= directory
26 of the Org distribution to the Emacs =load-path=.
27
28 - =org-colview-xemacs.el=
29 - =org-mew.el=
30 - =org-wl.el=
31 - =org-w3m.el=
32 - =org-vm.el=
33 - =ox-taskjuggler.el= (was org-taskjuggler.el)
34 - =ox-freemind.el= (was org-freemind.el)
35
36 * Original announcement of the merge of the new exporter
37
38 Nicolas announced the merge of the new exporter into the master branch [[http://article.gmane.org/gmane.emacs.orgmode/65574][in
39 this email to the list]] -- maybe you'll find answers to your questions here,
40 please have a look.
41
42 * Updating global export configuration options
43
44 Global export options start with the =org-export-*= prefix, most of them
45 are in the =ox.el= file.
46
47 For options starting with e.g. =org-export-html-*=, see the section below.
48
49 For generic export options, most of them should not need any change.  If
50 you find that a generic option is useless or broken or badly documented in
51 the manual, please report it to the list.
52
53 * New global keywords
54
55 ** New #+TOC keyword
56
57 There is a new =#+TOC= which allow adding more "table of contents" for the
58 LaTeX backend (for now).
59
60 #+BEGIN_SRC org
61   ,#+TOC: headlines 2
62   ,#+TOC: figures
63   ,#+TOC: tables
64   ,#+TOC: listings
65 #+END_SRC
66
67 This will add the corresponding tables of contents.
68 For now, the ODT backend only supports "headlines"
69
70 See the "Table of contents" section in the manual.
71
72 * Updating backend-specific configuration options
73
74 Backend-specific options are defined like this:
75
76 - =org-html-*= for =HTML= and live in =ox-html.el=
77 - =org-latex-*= for =LaTeX= and live in =ox-latex.el=
78 - Etc.
79
80 There is a new variable =org-export-backends= which controls what backends
81 are loaded when you lauch Org.  By default, the =ASCII=, =HTML= and =LaTeX=
82 are loaded, with some others.
83
84 *Updating*: In your =.emacs= you need to rename =org-export-html-*= options
85 to =org-html-*= and do the same for other backends.
86
87 ** Renaming/deleting of some HTML options
88
89 | Org 7.9.3f (maint)                     | Master (8.0)                           |
90 |----------------------------------------+----------------------------------------|
91 | org-export-html-style                  | org-html-head                          |
92 | org-export-html-style-extra            | org-html-head-extra                    |
93 | org-export-html-style-default          | org-html-head-include-default-style    |
94 | org-export-html-style-include-scripts  | org-html-head-include-scripts          |
95 | org-export-htmlized-org-css-url        | org-org-htmlized-css-url (in ox-org.el |
96 |----------------------------------------+----------------------------------------|
97 | org-export-html-headline-anchor-format | Deleted                                |
98 | org-export-html-date-format-string     | Deteted                                |
99 | org-export-html-content-div            | Deleted                                |
100 | org-export-html-html-helper-timestamp  | Deleted                                |
101
102 * Updating =org-publish-project-alist=
103
104 The publishing functions are not loaded until the corresponding backend has
105 been loaded.  You need to update =org-publish-project-alist= and to use the
106 function from the new publishing engine -- here is correspondance table:
107
108 | Old publishing engine    | New publishing engine      |
109 |--------------------------+----------------------------|
110 | org-publish-org-to-html  | org-html-publish-to-html   |
111 | org-publish-org-to-org   | org-org-publish-to-org     |
112 | org-publish-org-to-latex | org-latex-publish-to-latex |
113 | ...                      | ...                        |
114
115 If something does not work, please report it on the mailing list.
116
117 * Other important changes
118
119 1. =#+STYLE:= -> =#+HTML_HEAD:=
120
121 2. =#+SETUPFILE: myfile= -> =#+INCLUDE: "myfile"=
122
123    Quotes are required and =#+INCLUDE= works a little differently
124    than #+setupfile: by default, it makes sure that every headline in the
125    included file will be a child of the headline containing the include
126    keyword.  You can overwrite this behaviour with =:minlevel= num
127    parameter.
128
129 1. Attribute lines now take plists:
130
131    : #+attr_latex :width 5cm
132    : #+attr_beamer :options width=5cm
133
134 2. Beamer backend now interprets nested headline levels as blocks instead
135    of lists.  For some preliminary guidance you can look at [[file:exporters/beamer/ox-beamer.org][this page]].
136
137 * Using Org 7.9.3f or earlier versions of Org
138
139 1. If you had already been using the new exporter from contrib, you should
140    remove the following lines from your local.mk:
141    : ORG_ADD_CONTRIB = org-e-*
142    followed by a =make clean=, before you do =git pull=.
143
144 2. Export engine renamed: org-export → ox
145
146 3. Backend requires renamed: org-e-* → ox-*
147
148 4. All backend specific variables and functions renamed:
149    - org-export-* → org-* (e.g. org-html-xml-declaration, ..)
150    - org-e-* → org-* (e.g. org-latex-classes, org-ascii-bullets, ..)
151
152 5. Generic export variables retain the name org-export-*
153    (e.g. org-export-dispatch-use-expert-ui,
154    org-export-filter-headline-functions, ..)
155
156 6. org-latex-to-pdf-process has been renamed to org-latex-pdf-process
157
158 7. This is a guess, export snippets and backend symbols renamed:
159    - e-<backend> → <backend>
160
161 Please also read [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge.
162