org-8.0: Fix #+toc description, add export snippets
[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 allows adding table of contents, lists of
58 tables and lists of listings at specific locations during export.
59
60 #+BEGIN_SRC org
61   ,#+TOC: headlines 2
62   ,#+TOC: tables
63   ,#+TOC: listings
64 #+END_SRC
65
66 See the "Table of contents" section in the manual.
67
68 * New syntax
69
70 ** Export snippets
71
72    Export snippets are a generalization of ~@<tag>~ concept, which has
73    been removed, and the inline version of
74    ~#+begin_backend...#+end_backend~ blocks.
75
76    Their syntax is ~@@backend:value~ where ~backend~ is the targetted
77    export backend (e.g. ~html~) and ~value~ can contain anything but
78    ~@@~.
79
80    When export is done with ~backend~, the snippet is replaced with
81    ~value~, otherwise it is removed.  Whitespace characters around
82    the construct are never deleted.
83
84 * Updating backend-specific configuration options
85
86 Backend-specific options are defined like this:
87
88 - =org-html-*= for =HTML= and live in =ox-html.el=
89 - =org-latex-*= for =LaTeX= and live in =ox-latex.el=
90 - Etc.
91
92 There is a new variable =org-export-backends= which controls what backends
93 are loaded when you lauch Org.  By default, the =ASCII=, =HTML= and =LaTeX=
94 are loaded, with some others.
95
96 *Updating*: In your =.emacs= you need to rename =org-export-html-*= options
97 to =org-html-*= and do the same for other backends.
98
99 ** Renaming/deleting of some HTML options
100
101 | Org 7.9.3f (maint)                     | Master (8.0)                           |
102 |----------------------------------------+----------------------------------------|
103 | org-export-html-style                  | org-html-head                          |
104 | org-export-html-style-extra            | org-html-head-extra                    |
105 | org-export-html-style-default          | org-html-head-include-default-style    |
106 | org-export-html-style-include-scripts  | org-html-head-include-scripts          |
107 | org-export-htmlized-org-css-url        | org-org-htmlized-css-url (in ox-org.el |
108 |----------------------------------------+----------------------------------------|
109 | org-export-html-headline-anchor-format | Deleted                                |
110 | org-export-html-date-format-string     | Deteted                                |
111 | org-export-html-content-div            | Deleted                                |
112 | org-export-html-html-helper-timestamp  | Deleted                                |
113
114 * Updating =org-publish-project-alist=
115
116 The publishing functions are not loaded until the corresponding backend has
117 been loaded.  You need to update =org-publish-project-alist= and to use the
118 function from the new publishing engine -- here is correspondance table:
119
120 | Old publishing engine    | New publishing engine      |
121 |--------------------------+----------------------------|
122 | org-publish-org-to-html  | org-html-publish-to-html   |
123 | org-publish-org-to-org   | org-org-publish-to-org     |
124 | org-publish-org-to-latex | org-latex-publish-to-latex |
125 | ...                      | ...                        |
126
127 If something does not work, please report it on the mailing list.
128
129 * Other important changes
130
131 1. =#+STYLE:= -> =#+HTML_HEAD:=
132
133 2. =#+SETUPFILE: myfile= versus =#+INCLUDE: "myfile".=
134
135    Both =#+SETUPFILE:= and =#+INCLUDE:= now need quotes around the
136    file name.  There is now also a clear difference between these two
137    statements.  The first will only read keyword statements like
138    =#+TODO:= and use this to set up the current file.  The second will
139    pull in the entire content of the file during export.  The
140    =#+INCLUDE:= statement will make every headline in the included
141    file will be a child of the headline containing the include
142    keyword.  You can overwrite this behaviour with =:minlevel= num
143    parameter.
144
145 1. Attribute lines now take plists:
146
147    : #+attr_latex :width 5cm
148    : #+attr_beamer :options width=5cm
149
150 2. Beamer backend now interprets nested headline levels as blocks instead
151    of lists.  For some preliminary guidance you can look at [[file:exporters/beamer/ox-beamer.org][this page]].
152
153 * Using Org 7.9.3f or earlier versions of Org
154
155 1. If you had already been using the new exporter from contrib, you should
156    remove the following lines from your local.mk:
157    : ORG_ADD_CONTRIB = org-e-*
158    followed by a =make clean=, before you do =git pull=.
159
160 2. Export engine renamed: org-export → ox
161
162 3. Backend requires renamed: org-e-* → ox-*
163
164 4. All backend specific variables and functions renamed:
165    - org-export-* → org-* (e.g. org-html-xml-declaration, ..)
166    - org-e-* → org-* (e.g. org-latex-classes, org-ascii-bullets, ..)
167
168 5. Generic export variables retain the name org-export-*
169    (e.g. org-export-dispatch-use-expert-ui,
170    org-export-filter-headline-functions, ..)
171
172 6. org-latex-to-pdf-process has been renamed to org-latex-pdf-process
173
174 7. This is a guess, export snippets and backend symbols renamed:
175    - e-<backend> → <backend>
176
177 Please also read [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge.
178