346796a663af2c5883110036e7f5aa9b14fea93a
[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= versus =#+INCLUDE: "myfile".=
122
123    Both =#+SETUPFILE:= and =#+INCLUDE:= now need quotes around the
124    file name.  There is now also a clear difference between these two
125    statements.  The first will only read keyword statements like
126    =#+TODO:= and use this to set up the current file.  Thesecond will
127    pull in the entire content of the file during export.  The
128    =#+INCLUDE:= statement will make every headline in the included
129    file will be a child of the headline containing the include
130    keyword.  You can overwrite this behaviour with =:minlevel= num
131    parameter.
132
133 1. Attribute lines now take plists:
134
135    : #+attr_latex :width 5cm
136    : #+attr_beamer :options width=5cm
137
138 2. Beamer backend now interprets nested headline levels as blocks instead
139    of lists.  For some preliminary guidance you can look at [[file:exporters/beamer/ox-beamer.org][this page]].
140
141 * Using Org 7.9.3f or earlier versions of Org
142
143 1. If you had already been using the new exporter from contrib, you should
144    remove the following lines from your local.mk:
145    : ORG_ADD_CONTRIB = org-e-*
146    followed by a =make clean=, before you do =git pull=.
147
148 2. Export engine renamed: org-export → ox
149
150 3. Backend requires renamed: org-e-* → ox-*
151
152 4. All backend specific variables and functions renamed:
153    - org-export-* → org-* (e.g. org-html-xml-declaration, ..)
154    - org-e-* → org-* (e.g. org-latex-classes, org-ascii-bullets, ..)
155
156 5. Generic export variables retain the name org-export-*
157    (e.g. org-export-dispatch-use-expert-ui,
158    org-export-filter-headline-functions, ..)
159
160 6. org-latex-to-pdf-process has been renamed to org-latex-pdf-process
161
162 7. This is a guess, export snippets and backend symbols renamed:
163    - e-<backend> → <backend>
164
165 Please also read [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge.
166