added table of exporters to be udpated with links to corresponding exporter tutorials
[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 * Syntax changes
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 ** Footnote definitions
85
86    A footnote definition (not inline) can now be ended with two
87    consecutive blank lines.
88
89    As a consequence, multiple paragraphs inside can be written
90    normally, separated with blank lines, instead of relying on the
91    ~\par~ command.
92
93 * Updating backend-specific configuration options
94
95 Backend-specific options are defined like this:
96
97 - =org-html-*= for =HTML= and live in =ox-html.el=
98 - =org-latex-*= for =LaTeX= and live in =ox-latex.el=
99 - Etc.
100
101 There is a new variable =org-export-backends= which controls what backends
102 are loaded when you lauch Org.  By default, the =ASCII=, =HTML= and =LaTeX=
103 are loaded, with some others.
104
105 *Updating*: In your =.emacs= you need to rename =org-export-html-*= options
106 to =org-html-*= and do the same for other backends.
107
108 ** Renaming/deleting of some HTML options
109
110 | Org 7.9.3f (maint)                     | Master (8.0)                           |
111 |----------------------------------------+----------------------------------------|
112 | org-export-html-style                  | org-html-head                          |
113 | org-export-html-style-extra            | org-html-head-extra                    |
114 | org-export-html-style-default          | org-html-head-include-default-style    |
115 | org-export-html-style-include-scripts  | org-html-head-include-scripts          |
116 | org-export-htmlized-org-css-url        | org-org-htmlized-css-url (in ox-org.el |
117 |----------------------------------------+----------------------------------------|
118 | org-export-html-headline-anchor-format | Deleted                                |
119 | org-export-html-date-format-string     | Deteted                                |
120 | org-export-html-content-div            | Deleted                                |
121 | org-export-html-html-helper-timestamp  | Deleted                                |
122
123 * Updating =org-publish-project-alist=
124
125 The publishing functions are not loaded until the corresponding backend has
126 been loaded.  You need to update =org-publish-project-alist= and to use the
127 function from the new publishing engine -- here is correspondance table:
128
129 | Old publishing engine    | New publishing engine      |
130 |--------------------------+----------------------------|
131 | org-publish-org-to-html  | org-html-publish-to-html   |
132 | org-publish-org-to-org   | org-org-publish-to-org     |
133 | org-publish-org-to-latex | org-latex-publish-to-latex |
134 | ...                      | ...                        |
135
136 If something does not work, please report it on the mailing list.
137
138 * Other important changes
139
140 1. =#+STYLE:= -> =#+HTML_HEAD:=
141
142 2. =#+SETUPFILE: myfile= versus =#+INCLUDE: "myfile".=
143
144    Both =#+SETUPFILE:= and =#+INCLUDE:= now need quotes around the
145    file name.  There is now also a clear difference between these two
146    statements.  The first will only read keyword statements like
147    =#+TODO:= and use this to set up the current file.  The second will
148    pull in the entire content of the file during export.  The
149    =#+INCLUDE:= statement will make every headline in the included
150    file will be a child of the headline containing the include
151    keyword.  You can overwrite this behaviour with =:minlevel= num
152    parameter.
153
154 1. Attribute lines now take plists:
155
156    : #+attr_latex :width 5cm
157    : #+attr_beamer :options width=5cm
158
159 2. Beamer backend now interprets nested headline levels as blocks instead
160    of lists.  For some preliminary guidance you can look at [[file:exporters/beamer/ox-beamer.org][this page]].
161
162 * Using Org 7.9.3f or earlier versions of Org
163
164 1. If you had already been using the new exporter from contrib, you should
165    remove the following lines from your local.mk:
166    : ORG_ADD_CONTRIB = org-e-*
167    followed by a =make clean=, before you do =git pull=.
168
169 2. Export engine renamed: org-export → ox
170
171 3. Backend requires renamed: org-e-* → ox-*
172
173 4. All backend specific variables and functions renamed:
174    - org-export-* → org-* (e.g. org-html-xml-declaration, ..)
175    - org-e-* → org-* (e.g. org-latex-classes, org-ascii-bullets, ..)
176
177 5. Generic export variables retain the name org-export-*
178    (e.g. org-export-dispatch-use-expert-ui,
179    org-export-filter-headline-functions, ..)
180
181 6. org-latex-to-pdf-process has been renamed to org-latex-pdf-process
182
183 7. This is a guess, export snippets and backend symbols renamed:
184    - e-<backend> → <backend>
185
186 Please also read [[http://mid.gmane.org/876229nrxf.fsf@gmail.com][Nicolas' announcement]] about the merge.
187
188 * List of current Org-mode exporters
189
190 Please find below a list of current Org-mode exporters, the location of the backend elisp
191 file (relative to downloaded Org-mode installation directory, =org=), and links to their
192 corresponding detailed tutorial pages:
193
194 | *Name*        | *Exporter location*                | *Tutorial*     |
195 |---------------+------------------------------------+----------------|
196 | ASCII         | =./lisp/ox-ascii.el=               | ox-ascii       |
197 | [[https://bitbucket.org/rivanvx/beamer/wiki/Home][Beamer]]        | =./lisp/ox-beamer.el=              | ox-beamer      |
198 | html          | =./lisp/ox-html.el=                | ox-html        |
199 | [[http://en.wikipedia.org/wiki/ICalendar][iCalendar]]     | =./lisp/ox-icalandar.el=           | ox-icalendar   |
200 | [[http://www.latex-project.org/][LaTeX]]         | =./lisp/ox-latex.el=               | ox-latex       |
201 | [[http://manpages.bsd.lv/history.html][Man]]           | =./lisp/ox-man.el=                 | ox-man         |
202 | [[http://daringfireball.net/projects/markdown/][Markdown]]      | =./lisp/ox-md.el=                  | ox-md          |
203 | [[http://opendocumentformat.org/][ODT]]           | =./lisp/ox-odt.el=                 | ox-odt         |
204 | [[http://orgmode.org/manual/Publishing.html][Publishing]]    | =./lisp/ox-publish.el=             | ox-publish     |
205 | [[http://www.gnu.org/software/texinfo/][Texinfo]]       | =./lisp/ox-texinfo.el=             | ox-texinfo     |
206 |---------------+------------------------------------+----------------|
207 | [[http://www.atlassian.com/software/confluence/overview/team-collaboration-software][Confluence]]    | =./contrib/lisp/ox-confluence.el=  | ox-confluence  |
208 | [[http://imakewebthings.com/deck.js/][Deck.js]]       | =./contrib/lisp/ox-deck.el=        | ox-deck        |
209 | [[http://freemind.sourceforge.net/wiki/index.php/Main_Page][Freemind]]      | =./contrib/lisp/ox-freemind.el=    | ox-freemind    |
210 | [[http://www.gnu.org/software/groff/][Groff]]         | =./contrib/lisp/ox-groff.el=       | ox-groff       |
211 | [[http://www.ctan.org/pkg/koma-script][Koma Scrlttr2]] | =./contrib/lisp/ox-koma-letter.el= | ox-koma-letter |
212 | [[http://www.rssboard.org/rss-specification][RSS]]           | =./contrib/lisp/ox-rss.el=         | ox-rss         |
213 | [[http://meyerweb.com/eric/tools/s5/][S5]]            | =./contrib/lisp/ox-s5.el=          | ox-s5          |
214 | [[http://www.taskjuggler.org/][Taskjuggler]]   | =./contrib/lisp/ox-taskjuggler.el= | ox-taskjuggler |
215
216