aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorBastien Guerry2012-04-01 11:49:25 +0200
committerBastien Guerry2012-04-01 11:49:25 +0200
commit153ae947f845f6d4f31d3d239a1449899c3384f0 (patch)
treeb7ef6c7f4b94f4a4ee19eecd079c36aff84bddc5 /doc
parent42ee526b1adbe2ba7766203980a9d7089aae1a68 (diff)
downloademacs-153ae947f845f6d4f31d3d239a1449899c3384f0.tar.gz
emacs-153ae947f845f6d4f31d3d239a1449899c3384f0.zip
Update to Org version 7.8.07 (commit da0e6f in Org's repo)
Diffstat (limited to 'doc')
-rw-r--r--doc/misc/ChangeLog112
-rw-r--r--doc/misc/org.texi597
2 files changed, 481 insertions, 228 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 8d40ab5ab15..6c8a9d29c2e 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,115 @@
12012-04-01 Jambunathan K <kjambunathan@gmail.com>
2
3 * org.texi (Customizing tables in ODT export): Correct few errors.
4
52012-04-01 Jambunathan K <kjambunathan@gmail.com>
6
7 * org.texi (Links in ODT export): Update.
8 (Labels and captions in ODT export): New node.
9
102012-04-01 Jambunathan K <kjambunathan@gmail.com>
11
12 * org.texi (Literal examples in ODT export): htmlfontify.el in
13 Emacs-24.1 now supports fontification. So ODT source blocks will
14 be fontified by default.
15
162012-04-01 Julian Gehring <julian.gehring@googlemail.com> (tiny change)
17
18 * org.texi (Refiling notes): Remove duplicated keybinding.
19
202012-04-01 Eric Schulte <eric.schulte@gmx.com>
21
22 * org.texi (noweb): Documentation of this new option to the :noweb
23 header argument.
24
252012-04-01 Suvayu Ali <fatkasuvayu+linux@gmail.com>
26
27 * org.texi (Header and sectioning): Add example demonstrating how
28 to use "LaTeX_CLASS_OPTIONS".
29
302012-04-01 Eric Schulte <eric.schulte@gmx.com>
31
32 * org.texi (Noweb reference syntax): Describe the ability to
33 execute noweb references in the manual.
34
352012-04-01 Eric Schulte <eric.schulte@gmx.com>
36
37 * org.texi (cache): Improve cache documentation when session
38 evaluation is used.
39
402012-04-01 Nicolas Goaziou <n.goaziou@gmail.com>
41
42 * org.texi (Plain lists): Document removal.
43
442012-04-01 Michael Brand <michael.ch.brand@gmail.com>
45
46 * org.texi: Decapitalize file name in references to Calc manual.
47
482012-04-01 Nicolas Goaziou <n.goaziou@gmail.com>
49
50 * org.texi (Plain lists): Document removal.
51
522012-04-01 Jambunathan K <kjambunathan@gmail.com>
53
54 * org.texi (Top, OpenDocument Text export)
55 (ODT export commands, Extending ODT export)
56 (Images in ODT export, Tables in ODT export)
57 (Configuring a document converter): Add or Update.
58
592012-04-01 Carsten Dominik <carsten.dominik@gmail.com>
60
61 * org.texi (MobileOrg): Change the wording to reflect that the
62 Android Version is no longer just the little brother of the iOS
63 version.
64
652012-04-01 Eric Schulte <eric.schulte@gmx.com>
66
67 * org.texi (Key bindings and useful functions): Updated babel key
68 binding documentation in manual.
69
702012-04-01 Eric Schulte <eric.schulte@gmx.com>
71
72 * org.texi (noweb): Document new noweb header value.
73
742012-04-01 Eric Schulte <eric.schulte@gmx.com>
75
76 * org.texi (noweb-sep): Document new header argument.
77
782012-04-01 Eric Schulte <eric.schulte@gmx.com>
79
80 * org.texi (noweb-ref): Documentation of this new custom variable.
81
822012-04-01 Eric Schulte <eric.schulte@gmx.com>
83
84 * org.texi (wrap): Update the new :wrap documentation to match the
85 current implementation.
86
872012-04-01 Thomas Dye <dk@poto.myhome.westell.com>
88
89 * org.texi: Added documentation for :wrap.
90
912012-04-01 Thomas Dye <dk@poto.myhome.westell.com>
92
93 * org.texi: #+RESULTS now user-configurable.
94
952012-04-01 Thomas Dye <dk@poto.myhome.westell.com>
96
97 * org.texi: Documented :noweb no-export.
98
992012-04-01 Thomas Dye <dk@poto.local>
100
101 * org.texi: Edit :noweb no header argument for correctness.
102
1032012-04-01 Bastien Guerry <bzg@altern.org>
104
105 * org.texi (Customization): Update the approximate number of Org
106 variables.
107
1082012-04-01 Thomas Dye <dk@poto.local>
109
110 * org.texi: The :results wrap produces a drawer instead of a
111 begin_results block.
112
12012-03-22 Peder O. Klingenberg <peder@klingenberg.no> (tiny change) 1132012-03-22 Peder O. Klingenberg <peder@klingenberg.no> (tiny change)
2 114
3 * gnus.texi (Archived Messages): Update `gnus-message-archive-group' to 115 * gnus.texi (Archived Messages): Update `gnus-message-archive-group' to
diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index 2a41d6b9301..ab9de71277f 100644
--- a/doc/misc/org.texi
+++ b/doc/misc/org.texi
@@ -4,8 +4,8 @@
4@setfilename ../../info/org 4@setfilename ../../info/org
5@settitle The Org Manual 5@settitle The Org Manual
6 6
7@set VERSION 7.8.03 7@set VERSION 7.8.07
8@set DATE January 2012 8@set DATE March 2012
9 9
10@c Use proper quote and backtick for code sections in PDF output 10@c Use proper quote and backtick for code sections in PDF output
11@c Cf. Texinfo manual 14.2 11@c Cf. Texinfo manual 14.2
@@ -265,7 +265,7 @@
265@copying 265@copying
266This manual is for Org version @value{VERSION}. 266This manual is for Org version @value{VERSION}.
267 267
268Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. 268Copyright @copyright{} 2004-2011 Free Software Foundation, Inc.
269 269
270@quotation 270@quotation
271Permission is granted to copy, distribute and/or modify this document 271Permission is granted to copy, distribute and/or modify this document
@@ -612,27 +612,29 @@ DocBook export
612 612
613OpenDocument Text export 613OpenDocument Text export
614 614
615* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on 615* Pre-requisites for ODT export:: What packages ODT exporter relies on
616* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export 616* ODT export commands:: How to invoke ODT export
617* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
617* Applying custom styles:: How to apply custom styles to the output 618* Applying custom styles:: How to apply custom styles to the output
618* Links in @acronym{ODT} export:: How links will be interpreted and formatted 619* Links in ODT export:: How links will be interpreted and formatted
619* Tables in @acronym{ODT} export:: How Tables are exported 620* Tables in ODT export:: How Tables are exported
620* Images in @acronym{ODT} export:: How to insert images 621* Images in ODT export:: How to insert images
621* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted 622* Math formatting in ODT export:: How @LaTeX{} fragments are formatted
622* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted 623* Labels and captions in ODT export:: How captions are rendered
623* Advanced topics in @acronym{ODT} export:: Read this if you are a power user 624* Literal examples in ODT export:: How source and example blocks are formatted
625* Advanced topics in ODT export:: Read this if you are a power user
624 626
625Math formatting in @acronym{ODT} export 627Math formatting in ODT export
626 628
627* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments 629* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments
628* Working with MathML or OpenDocument formula files:: How to embed equations in native format 630* Working with MathML or OpenDocument formula files:: How to embed equations in native format
629 631
630Advanced topics in @acronym{ODT} export 632Advanced topics in ODT export
631 633
632* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats 634* Configuring a document converter:: How to register a document converter
633* Working with OpenDocument style files:: Explore the internals 635* Working with OpenDocument style files:: Explore the internals
634* Creating one-off styles:: How to produce custom highlighting etc 636* Creating one-off styles:: How to produce custom highlighting etc
635* Customizing tables in @acronym{ODT} export:: How to define and use Table templates 637* Customizing tables in ODT export:: How to define and use Table templates
636* Validating OpenDocument XML:: How to debug corrupt OpenDocument files 638* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
637 639
638Publishing 640Publishing
@@ -708,6 +710,7 @@ Specific header arguments
708* session:: Preserve the state of code evaluation 710* session:: Preserve the state of code evaluation
709* noweb:: Toggle expansion of noweb references 711* noweb:: Toggle expansion of noweb references
710* noweb-ref:: Specify block's noweb reference resolution target 712* noweb-ref:: Specify block's noweb reference resolution target
713* noweb-sep:: String used to separate noweb references
711* cache:: Avoid re-evaluating unchanged code blocks 714* cache:: Avoid re-evaluating unchanged code blocks
712* sep:: Delimiter for writing tabular results outside Org 715* sep:: Delimiter for writing tabular results outside Org
713* hlines:: Handle horizontal lines in tables 716* hlines:: Handle horizontal lines in tables
@@ -1004,7 +1007,7 @@ from within Emacs, please copy and paste the content into your Email program.
1004 1007
1005Sometimes you might face a problem due to an error in your Emacs or Org mode 1008Sometimes you might face a problem due to an error in your Emacs or Org mode
1006setup. Before reporting a bug, it is very helpful to start Emacs with minimal 1009setup. Before reporting a bug, it is very helpful to start Emacs with minimal
1007customizations and reproduce the problem. Doing so often helps you determine 1010customisations and reproduce the problem. Doing so often helps you determine
1008if the problem is with your customization or with Org mode itself. You can 1011if the problem is with your customization or with Org mode itself. You can
1009start a typical minimal session with a command like the example below. 1012start a typical minimal session with a command like the example below.
1010 1013
@@ -1435,8 +1438,7 @@ creation time, scheduled time, deadline time), by priority, by TODO keyword
1435(in the sequence the keywords have been defined in the setup) or by the value 1438(in the sequence the keywords have been defined in the setup) or by the value
1436of a property. Reverse sorting is possible as well. You can also supply 1439of a property. Reverse sorting is possible as well. You can also supply
1437your own function to extract the sorting key. With a @kbd{C-u} prefix, 1440your own function to extract the sorting key. With a @kbd{C-u} prefix,
1438sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes, duplicate 1441sorting will be case-sensitive.
1439entries will also be removed.
1440@orgcmd{C-x n s,org-narrow-to-subtree} 1442@orgcmd{C-x n s,org-narrow-to-subtree}
1441Narrow buffer to current subtree. 1443Narrow buffer to current subtree.
1442@orgcmd{C-x n b,org-narrow-to-block} 1444@orgcmd{C-x n b,org-narrow-to-block}
@@ -1587,16 +1589,11 @@ line. In particular, if an ordered list reaches number @samp{10.}, then the
1587list. An item ends before the next line that is less or equally indented 1589list. An item ends before the next line that is less or equally indented
1588than its bullet/number. 1590than its bullet/number.
1589 1591
1590@vindex org-list-ending-method
1591@vindex org-list-end-regexp
1592@vindex org-empty-line-terminates-plain-lists 1592@vindex org-empty-line-terminates-plain-lists
1593Two methods@footnote{To disable either of them, configure 1593A list ends whenever every item has ended, which means before any line less
1594@code{org-list-ending-method}.} are provided to terminate lists. A list ends 1594or equally indented than items at top level. It also ends before two blank
1595whenever every item has ended, which means before any line less or equally
1596indented than items at top level. It also ends before two blank
1597lines@footnote{See also @code{org-empty-line-terminates-plain-lists}.}. In 1595lines@footnote{See also @code{org-empty-line-terminates-plain-lists}.}. In
1598that case, all items are closed. For finer control, you can end lists with 1596that case, all items are closed. Here is an example:
1599any pattern set in @code{org-list-end-regexp}. Here is an example:
1600 1597
1601@example 1598@example
1602@group 1599@group
@@ -1949,13 +1946,7 @@ item.
1949 1946
1950Org comes with a fast and intuitive table editor. Spreadsheet-like 1947Org comes with a fast and intuitive table editor. Spreadsheet-like
1951calculations are supported using the Emacs @file{calc} package 1948calculations are supported using the Emacs @file{calc} package
1952@ifinfo 1949(@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
1953(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}).
1954@end ifinfo
1955@ifnotinfo
1956(see the Emacs Calculator manual for more information about the Emacs
1957calculator).
1958@end ifnotinfo
1959 1950
1960@menu 1951@menu
1961* Built-in table editor:: Simple tables 1952* Built-in table editor:: Simple tables
@@ -2253,7 +2244,8 @@ of columns, much like horizontal lines can do for groups of rows. In
2253order to specify column groups, you can use a special row where the 2244order to specify column groups, you can use a special row where the
2254first field contains only @samp{/}. The further fields can either 2245first field contains only @samp{/}. The further fields can either
2255contain @samp{<} to indicate that this column should start a group, 2246contain @samp{<} to indicate that this column should start a group,
2256@samp{>} to indicate the end of a column, or @samp{<>} to make a column 2247@samp{>} to indicate the end of a column, or @samp{<>} (no space between @samp{<}
2248and @samp{>}) to make a column
2257a group of its own. Boundaries between column groups will upon export be 2249a group of its own. Boundaries between column groups will upon export be
2258marked with vertical lines. Here is an example: 2250marked with vertical lines. Here is an example:
2259 2251
@@ -2515,9 +2507,8 @@ A formula can be any algebraic expression understood by the Emacs
2515non-standard convention that @samp{/} has lower precedence than 2507non-standard convention that @samp{/} has lower precedence than
2516@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before 2508@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before
2517evaluation by @code{calc-eval} (@pxref{Calling Calc from 2509evaluation by @code{calc-eval} (@pxref{Calling Calc from
2518Your Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNU 2510Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc, GNU
2519Emacs Calc Manual}), 2511Emacs Calc Manual}),
2520@c FIXME: The link to the Calc manual in HTML does not work.
2521variable substitution takes place according to the rules described above. 2512variable substitution takes place according to the rules described above.
2522@cindex vectors, in table calculations 2513@cindex vectors, in table calculations
2523The range vectors can be directly fed into the Calc vector functions 2514The range vectors can be directly fed into the Calc vector functions
@@ -5407,10 +5398,11 @@ the settings. This has been the source of much confusion. Org mode users
5407can resort to special versions of these functions like @code{org-date} or 5398can resort to special versions of these functions like @code{org-date} or
5408@code{org-anniversary}. These work just like the corresponding @code{diary-} 5399@code{org-anniversary}. These work just like the corresponding @code{diary-}
5409functions, but with stable ISO order of arguments (year, month, day) wherever 5400functions, but with stable ISO order of arguments (year, month, day) wherever
5410applicable, independent of the value of @code{calendar-date-style}.}. For example 5401applicable, independent of the value of @code{calendar-date-style}.}. For
5402example with optional time
5411 5403
5412@example 5404@example
5413* The nerd meeting on every 2nd Thursday of the month 5405* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
5414 <%%(org-float t 4 2)> 5406 <%%(org-float t 4 2)>
5415@end example 5407@end example
5416 5408
@@ -6162,7 +6154,7 @@ applying it to another one.
6162By customizing the variable @code{org-clock-idle-time} to some integer, such 6154By customizing the variable @code{org-clock-idle-time} to some integer, such
6163as 10 or 15, Emacs can alert you when you get back to your computer after 6155as 10 or 15, Emacs can alert you when you get back to your computer after
6164being idle for that many minutes@footnote{On computers using Mac OS X, 6156being idle for that many minutes@footnote{On computers using Mac OS X,
6165idleness is based on actual user idleness, not just Emacs's idle time. For 6157idleness is based on actual user idleness, not just Emacs' idle time. For
6166X11, you can install a utility program @file{x11idle.c}, available in the 6158X11, you can install a utility program @file{x11idle.c}, available in the
6167UTILITIES directory of the Org git distribution, to get the same general 6159UTILITIES directory of the Org git distribution, to get the same general
6168treatment of idleness. On other systems, idle time refers to Emacs idle time 6160treatment of idleness. On other systems, idle time refers to Emacs idle time
@@ -6905,10 +6897,7 @@ Use the refile interface to jump to a heading.
6905Jump to the location where @code{org-refile} last moved a tree to. 6897Jump to the location where @code{org-refile} last moved a tree to.
6906@item C-2 C-c C-w 6898@item C-2 C-c C-w
6907Refile as the child of the item currently being clocked. 6899Refile as the child of the item currently being clocked.
6908@item C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w
6909
6910@orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear} 6900@orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear}
6911
6912Clear the target cache. Caching of refile targets can be turned on by 6901Clear the target cache. Caching of refile targets can be turned on by
6913setting @code{org-refile-use-cache}. To make the command see new possible 6902setting @code{org-refile-use-cache}. To make the command see new possible
6914targets, you have to clear the cache with this command. 6903targets, you have to clear the cache with this command.
@@ -9548,7 +9537,7 @@ the web, while the XOXO format provides a solid base for exchange with a
9548broad range of other applications. @LaTeX{} export lets you use Org mode and 9537broad range of other applications. @LaTeX{} export lets you use Org mode and
9549its structured editing functions to easily create @LaTeX{} files. DocBook 9538its structured editing functions to easily create @LaTeX{} files. DocBook
9550export makes it possible to convert Org files to many other formats using 9539export makes it possible to convert Org files to many other formats using
9551DocBook tools. OpenDocument Text(@acronym{ODT}) export allows seamless 9540DocBook tools. OpenDocument Text(ODT) export allows seamless
9552collaboration across organizational boundaries. For project management you 9541collaboration across organizational boundaries. For project management you
9553can create gantt and resource charts by using TaskJuggler export. To 9542can create gantt and resource charts by using TaskJuggler export. To
9554incorporate entries with associated times like deadlines or appointments into 9543incorporate entries with associated times like deadlines or appointments into
@@ -10803,34 +10792,36 @@ special characters included in XHTML entities:
10803@cindex org-modules 10792@cindex org-modules
10804 10793
10805Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text 10794Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
10806(@acronym{ODT}) format using the @file{org-odt.el} module. Documents created 10795(ODT) format using the @file{org-odt.el} module. Documents created
10807by this exporter use the @cite{OpenDocument-v1.2 10796by this exporter use the @cite{OpenDocument-v1.2
10808specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, 10797specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
10809Open Document Format for Office Applications (OpenDocument) Version 1.2}} and 10798Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
10810are compatible with LibreOffice 3.4. 10799are compatible with LibreOffice 3.4.
10811 10800
10812@menu 10801@menu
10813* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on 10802* Pre-requisites for ODT export:: What packages ODT exporter relies on
10814* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export 10803* ODT export commands:: How to invoke ODT export
10804* Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
10815* Applying custom styles:: How to apply custom styles to the output 10805* Applying custom styles:: How to apply custom styles to the output
10816* Links in @acronym{ODT} export:: How links will be interpreted and formatted 10806* Links in ODT export:: How links will be interpreted and formatted
10817* Tables in @acronym{ODT} export:: How Tables are exported 10807* Tables in ODT export:: How Tables are exported
10818* Images in @acronym{ODT} export:: How to insert images 10808* Images in ODT export:: How to insert images
10819* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted 10809* Math formatting in ODT export:: How @LaTeX{} fragments are formatted
10820* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted 10810* Labels and captions in ODT export:: How captions are rendered
10821* Advanced topics in @acronym{ODT} export:: Read this if you are a power user 10811* Literal examples in ODT export:: How source and example blocks are formatted
10812* Advanced topics in ODT export:: Read this if you are a power user
10822@end menu 10813@end menu
10823 10814
10824@node Pre-requisites for @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export, OpenDocument Text export 10815@node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export
10825@subsection Pre-requisites for @acronym{ODT} export 10816@subsection Pre-requisites for ODT export
10826@cindex zip 10817@cindex zip
10827The @acronym{ODT} exporter relies on the @file{zip} program to create the final 10818The ODT exporter relies on the @file{zip} program to create the final
10828output. Check the availability of this program before proceeding further. 10819output. Check the availability of this program before proceeding further.
10829 10820
10830@node @acronym{ODT} export commands, Applying custom styles, Pre-requisites for @acronym{ODT} export, OpenDocument Text export 10821@node ODT export commands, Extending ODT export, Pre-requisites for ODT export, OpenDocument Text export
10831@subsection @acronym{ODT} export commands 10822@subsection ODT export commands
10832 10823
10833@subsubheading Exporting to @acronym{ODT} 10824@subsubheading Exporting to ODT
10834@anchor{x-export-to-odt} 10825@anchor{x-export-to-odt}
10835 10826
10836@cindex region, active 10827@cindex region, active
@@ -10841,12 +10832,13 @@ output. Check the availability of this program before proceeding further.
10841@cindex property EXPORT_FILE_NAME 10832@cindex property EXPORT_FILE_NAME
10842 10833
10843Export as OpenDocument Text file. 10834Export as OpenDocument Text file.
10835
10844@vindex org-export-odt-preferred-output-format 10836@vindex org-export-odt-preferred-output-format
10845If @code{org-export-odt-preferred-output-format} is specified, automatically 10837If @code{org-export-odt-preferred-output-format} is specified, automatically
10846convert the exported file to that format. 10838convert the exported file to that format. @xref{x-export-to-other-formats, ,
10847@xref{x-export-to-other-formats,,Automatically exporting to other formats}. 10839Automatically exporting to other formats}.
10848 10840
10849For an Org file @file{myfile.org}, the @acronym{ODT} file will be 10841For an Org file @file{myfile.org}, the ODT file will be
10850@file{myfile.odt}. The file will be overwritten without warning. If there 10842@file{myfile.odt}. The file will be overwritten without warning. If there
10851is an active region,@footnote{This requires @code{transient-mark-mode} to be 10843is an active region,@footnote{This requires @code{transient-mark-mode} to be
10852turned on} only the region will be exported. If the selected region is a 10844turned on} only the region will be exported. If the selected region is a
@@ -10857,30 +10849,66 @@ export.
10857 10849
10858@orgcmd{C-c C-e O,org-export-as-odt-and-open} 10850@orgcmd{C-c C-e O,org-export-as-odt-and-open}
10859Export as OpenDocument Text file and open the resulting file. 10851Export as OpenDocument Text file and open the resulting file.
10852
10860@vindex org-export-odt-preferred-output-format 10853@vindex org-export-odt-preferred-output-format
10861If @code{org-export-odt-preferred-output-format} is specified, open the 10854If @code{org-export-odt-preferred-output-format} is specified, open the
10862converted file instead. 10855converted file instead. @xref{x-export-to-other-formats, , Automatically
10863@xref{x-export-to-other-formats,,Automatically exporting to other formats}. 10856exporting to other formats}.
10864@end table 10857@end table
10865 10858
10866@subsubheading Automatically exporting to other formats 10859@node Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export
10860@subsection Extending ODT export
10861
10862The ODT exporter can interface with a variety of document
10863converters and supports popular converters out of the box. As a result, you
10864can use it to export to formats like @samp{doc} or convert a document from
10865one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}).
10866
10867@cindex @file{unoconv}
10868@cindex LibreOffice
10869If you have a working installation of LibreOffice, a document converter is
10870pre-configured for you and you can use it right away. If you would like to
10871use @file{unoconv} as your preferred converter, customize the variable
10872@code{org-export-odt-convert-process} to point to @code{unoconv}. If you
10873would like to use a converter of your own choosing or tweak the default
10874settings of the default @file{LibreOffice} and @samp{unoconv} converters
10875@xref{Configuring a document converter}.
10876
10877@subsubsection Automatically exporting to other formats
10867@anchor{x-export-to-other-formats} 10878@anchor{x-export-to-other-formats}
10879
10868@vindex org-export-odt-preferred-output-format 10880@vindex org-export-odt-preferred-output-format
10869Very often, you will find yourself exporting to @acronym{ODT} format, only to 10881Very often, you will find yourself exporting to ODT format, only to
10870immediately save the exported document to a different format like @samp{pdf}. 10882immediately save the exported document to other formats like @samp{doc},
10871In such cases, you will find it convenient to configure a converter 10883@samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your
10872(@pxref{Exporting and converting to other formats}) and specify your
10873preferred output format by customizing the variable 10884preferred output format by customizing the variable
10874@code{org-export-odt-preferred-output-format}. This way, the export commands 10885@code{org-export-odt-preferred-output-format}. This way, the export commands
10875(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to also export to 10886(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a
10876the preferred format. 10887format that is of immediate interest to you.
10888
10889@subsubsection Converting between document formats
10890@anchor{x-convert-to-other-formats}
10891
10892There are many document converters in the wild which support conversion to
10893and from various file formats, including, but not limited to the
10894ODT format. LibreOffice converter, mentioned above, is one such
10895converter. Once a converter is configured, you can interact with it using
10896the following command.
10877 10897
10878@node Applying custom styles, Links in @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export 10898@vindex org-export-odt-convert
10899@table @kbd
10900
10901@item M-x org-export-odt-convert
10902Convert an existing document from one format to another. With a prefix
10903argument, also open the newly produced file.
10904@end table
10905
10906@node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export
10879@subsection Applying custom styles 10907@subsection Applying custom styles
10880@cindex styles, custom 10908@cindex styles, custom
10881@cindex template, custom 10909@cindex template, custom
10882 10910
10883The @acronym{ODT} exporter ships with a set of OpenDocument styles 10911The ODT exporter ships with a set of OpenDocument styles
10884(@pxref{Working with OpenDocument style files}) that ensure a well-formatted 10912(@pxref{Working with OpenDocument style files}) that ensure a well-formatted
10885output. These factory styles, however, may not cater to your specific 10913output. These factory styles, however, may not cater to your specific
10886tastes. To customize the output, you can either modify the above styles 10914tastes. To customize the output, you can either modify the above styles
@@ -10893,7 +10921,7 @@ users alike, and is described here.
10893@enumerate 10921@enumerate
10894@item 10922@item
10895Create a sample @file{example.org} file with the below settings and export it 10923Create a sample @file{example.org} file with the below settings and export it
10896to @acronym{ODT} format. 10924to ODT format.
10897 10925
10898@example 10926@example
10899#+OPTIONS: H:10 num:t 10927#+OPTIONS: H:10 num:t
@@ -10936,15 +10964,22 @@ met, the output is going to be less than satisfactory. So it is highly
10936recommended that you only work with templates that are directly derived from 10964recommended that you only work with templates that are directly derived from
10937the factory settings. 10965the factory settings.
10938 10966
10939@node Links in @acronym{ODT} export, Tables in @acronym{ODT} export, Applying custom styles, OpenDocument Text export 10967@node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export
10940@subsection Links in @acronym{ODT} export 10968@subsection Links in ODT export
10941@cindex tables, in DocBook export 10969@cindex tables, in DocBook export
10942 10970
10943The @acronym{ODT} exporter creates cross-references (aka bookmarks) for 10971ODT exporter creates native cross-references for internal links. It creates
10944internal links. It creates Internet-style links for all other links. 10972Internet-style links for all other links.
10973
10974A link with no description and destined to a regular (un-itemized) outline
10975heading is replaced with a cross-reference and section number of the heading.
10945 10976
10946@node Tables in @acronym{ODT} export, Images in @acronym{ODT} export, Links in @acronym{ODT} export, OpenDocument Text export 10977A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced
10947@subsection Tables in @acronym{ODT} export 10978with a cross-reference and sequence number of the labelled entity.
10979@xref{Labels and captions in ODT export}.
10980
10981@node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export
10982@subsection Tables in ODT export
10948@cindex tables, in DocBook export 10983@cindex tables, in DocBook export
10949 10984
10950Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el} 10985Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el}
@@ -10952,21 +10987,47 @@ tables is supported. However, export of complex @file{table.el} tables -
10952tables that have column or row spans - is not supported. Such tables are 10987tables that have column or row spans - is not supported. Such tables are
10953stripped from the exported document. 10988stripped from the exported document.
10954 10989
10955By default, a table is exported with top and bottom frames and with 10990By default, a table is exported with top and bottom frames and with rules
10956rules separating row and column groups (@pxref{Column groups}). If the table 10991separating row and column groups (@pxref{Column groups}). Furthermore, all
10957specifies alignment and relative width for its columns (@pxref{Column width 10992tables are typeset to occupy the same width. If the table specifies
10958and alignment}) then these are honored on export.@footnote{The column widths 10993alignment and relative width for its columns (@pxref{Column width and
10959are interpreted as weighted ratios with the default weight being 1} 10994alignment}) then these are honored on export.@footnote{The column widths are
10995interpreted as weighted ratios with the default weight being 1}
10960 10996
10961@cindex #+ATTR_ODT 10997@cindex #+ATTR_ODT
10962If you are not satisfied with the default formatting of tables, you can 10998You can control the width of the table by specifying @code{:rel-width}
10963create custom table styles and associate them with a table using 10999property using an @code{#+ATTR_ODT} line.
10964the @code{#+ATTR_ODT} line. @xref{Customizing tables in @acronym{ODT} export}. 11000
11001For example, consider the following table which makes use of all the rules
11002mentoned above.
11003
11004@example
11005#+ATTR_ODT: :rel-width 50
11006| Area/Month | Jan | Feb | Mar | Sum |
11007|---------------+-------+-------+-------+-------|
11008| / | < | | | < |
11009| <l13> | <r5> | <r5> | <r5> | <r6> |
11010| North America | 1 | 21 | 926 | 948 |
11011| Middle East | 6 | 75 | 844 | 925 |
11012| Asia Pacific | 9 | 27 | 790 | 826 |
11013|---------------+-------+-------+-------+-------|
11014| Sum | 16 | 123 | 2560 | 2699 |
11015@end example
11016
11017On export, the table will occupy 50% of text area. The columns will be sized
11018(roughly) in the ratio of 13:5:5:5:6. The first column will be left-aligned
11019and rest of the columns will be right-aligned. There will be vertical rules
11020after separating the header and last columns from other columns. There will
11021be horizontal rules separating the header and last rows from other rows.
11022
11023If you are not satisfied with the above formatting options, you can create
11024custom table styles and associate them with a table using the
11025@code{#+ATTR_ODT} line. @xref{Customizing tables in ODT export}.
10965 11026
10966@node Images in @acronym{ODT} export, Math formatting in @acronym{ODT} export, Tables in @acronym{ODT} export, OpenDocument Text export 11027@node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export
10967@subsection Images in @acronym{ODT} export 11028@subsection Images in ODT export
10968@cindex images, embedding in @acronym{ODT} 11029@cindex images, embedding in ODT
10969@cindex embedding images in @acronym{ODT} 11030@cindex embedding images in ODT
10970 11031
10971@subsubheading Embedding images 11032@subsubheading Embedding images
10972You can embed images within the exported document by providing a link to the 11033You can embed images within the exported document by providing a link to the
@@ -10993,14 +11054,21 @@ link to an image file. For example, to embed a image
10993 11054
10994@subsubheading Sizing and scaling of embedded images 11055@subsubheading Sizing and scaling of embedded images
10995 11056
11057@cindex #+ATTR_ODT
10996You can control the size and scale of the embedded images using the 11058You can control the size and scale of the embedded images using the
10997@code{#+ATTR_ODT} attribute. 11059@code{#+ATTR_ODT} attribute.
10998 11060
11061@cindex identify, ImageMagick
10999@vindex org-export-odt-pixels-per-inch 11062@vindex org-export-odt-pixels-per-inch
11000Note that the exporter specifies the desired size of the image in the final 11063The exporter specifies the desired size of the image in the final document in
11001document in units of centimeters. In order to scale the embedded images, the 11064units of centimeters. In order to scale the embedded images, the exporter
11002exporter needs to compute the size of the image. This is done by retrieving 11065queries for pixel dimensions of the images using one of a) ImageMagick's
11003the image size in pixels and converting the pixel units to centimeters using 11066@file{identify} program or b) Emacs `create-image' and `image-size'
11067APIs.@footnote{Use of @file{ImageMagick} is only desirable. However, if you
11068routinely produce documents that have large images or you export your Org
11069files that has images using a Emacs batch script, then the use of
11070@file{ImageMagick} is mandatory.} The pixel dimensions are subsequently
11071converted in to units of centimeters using
11004@code{org-export-odt-pixels-per-inch}. The default value of this variable is 11072@code{org-export-odt-pixels-per-inch}. The default value of this variable is
11005set to @code{display-pixels-per-inch}. You can tweak this variable to 11073set to @code{display-pixels-per-inch}. You can tweak this variable to
11006achieve the best results. 11074achieve the best results.
@@ -11008,7 +11076,6 @@ achieve the best results.
11008The examples below illustrate the various possibilities. 11076The examples below illustrate the various possibilities.
11009 11077
11010@table @asis 11078@table @asis
11011
11012@item Explicitly size the image 11079@item Explicitly size the image
11013To embed @file{img.png} as a 10 cm x 10 cm image, do the following: 11080To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
11014 11081
@@ -11044,17 +11111,31 @@ height:width ratio, do the following
11044@end example 11111@end example
11045@end table 11112@end table
11046 11113
11047@node Math formatting in @acronym{ODT} export, Literal examples in @acronym{ODT} export, Images in @acronym{ODT} export, OpenDocument Text export 11114@subsubheading Anchoring of images
11048@subsection Math formatting in @acronym{ODT} export 11115
11116@cindex #+ATTR_ODT
11117You can control the manner in which an image is anchored by setting the
11118@code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one
11119of the the following three values for the @code{:anchor} property -
11120@samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}.
11121
11122To create an image that is anchored to a page, do the following:
11123@example
11124#+ATTR_ODT: :anchor "page"
11125[[./img.png]]
11126@end example
11127
11128@node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export
11129@subsection Math formatting in ODT export
11049 11130
11050The @acronym{ODT} exporter has special support for handling math. 11131The ODT exporter has special support for handling math.
11051 11132
11052@menu 11133@menu
11053* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments 11134* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments
11054* Working with MathML or OpenDocument formula files:: How to embed equations in native format 11135* Working with MathML or OpenDocument formula files:: How to embed equations in native format
11055@end menu 11136@end menu
11056 11137
11057@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in @acronym{ODT} export, Math formatting in @acronym{ODT} export 11138@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export
11058@subsubsection Working with @LaTeX{} math snippets 11139@subsubsection Working with @LaTeX{} math snippets
11059 11140
11060@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT 11141@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT
@@ -11120,11 +11201,11 @@ resulting images are embedded in the exported document. This method requires
11120that the @file{dvipng} program be available on your system. 11201that the @file{dvipng} program be available on your system.
11121@end enumerate 11202@end enumerate
11122 11203
11123@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in @acronym{ODT} export 11204@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in ODT export
11124@subsubsection Working with MathML or OpenDocument formula files 11205@subsubsection Working with MathML or OpenDocument formula files
11125 11206
11126For various reasons, you may find embedding @LaTeX{} math snippets in an 11207For various reasons, you may find embedding @LaTeX{} math snippets in an
11127@acronym{ODT} document less than reliable. In that case, you can embed a 11208ODT document less than reliable. In that case, you can embed a
11128math equation by linking to its MathML(@file{.mml}) source or its 11209math equation by linking to its MathML(@file{.mml}) source or its
11129OpenDocument formula (@file{.odf}) file as shown below: 11210OpenDocument formula (@file{.odf}) file as shown below:
11130 11211
@@ -11138,102 +11219,95 @@ or
11138[[./equation.odf]] 11219[[./equation.odf]]
11139@end example 11220@end example
11140 11221
11141@node Literal examples in @acronym{ODT} export, Advanced topics in @acronym{ODT} export, Math formatting in @acronym{ODT} export, OpenDocument Text export 11222@node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export
11142@subsection Literal examples in @acronym{ODT} export 11223@subsection Labels and captions in ODT export
11143 11224
11144Export of literal examples (@pxref{Literal examples}) with full fontification 11225You can label and caption various category of objects - an inline image, a
11145is supported. This feature is enabled by default and is activated 11226table, a @LaTeX{} fragment or a Math formula - using @code{#+LABEL} and
11146automatically if an enhanced version of @file{htmlfontify.el} is available in 11227@code{#+CAPTION} lines. @xref{Images and tables}. ODT exporter enumerates
11147the @code{load-path}.@footnote{The @file{htmlfontify.el} that ships with 11228each labelled or captioned object of a given category separately. As a
11148standard Emacs <= 24.1 has no support for @acronym{ODT} fontification. A 11229result, each such object is assigned a sequence number based on order of it's
11149copy of the proposed version is available as an attachment to 11230appearance in the Org file.
11150@url{http://debbugs.gnu.org/cgi/bugreport.cgi?msg=5;filename=htmlfontify.el;att=9;bug=9914,
11151Emacs Bug #9914}.}
11152 11231
11153@vindex org-export-odt-fontify-srcblocks 11232In the exported document, a user-provided caption is augmented with the
11233category and sequence number. Consider the following inline image in an Org
11234file.
11235
11236@example
11237#+CAPTION: Bell curve
11238#+LABEL: fig:SED-HR4049
11239[[./img/a.png]]
11240@end example
11154 11241
11155The character styles used for fontification of the literal blocks are 11242It could be rendered as shown below in the exported document.
11156auto-generated by the exporter in conjunction with @file{htmlfontify.el}
11157library and need not be included in the default @file{styles.xml} file.
11158These auto-generated styles have the @samp{OrgSrc} prefix and inherit their color
11159based on the face used by Emacs @code{font-lock} library.
11160 11243
11161@vindex org-export-odt-create-custom-styles-for-srcblocks 11244@example
11162If you prefer to use your own custom styles for fontification and disable 11245Figure 2: Bell curve
11163their auto-generation altogether, you can do so by customizing the variable 11246@end example
11164@code{org-export-odt-create-custom-styles-for-srcblocks}. 11247
11248@vindex org-export-odt-category-strings
11249You can modify the category component of the caption by customizing the
11250variable @code{org-export-odt-category-strings}. For example, to tag all
11251embedded images with the string @samp{Illustration} (instead of the default
11252@samp{Figure}) use the following setting.
11253
11254@lisp
11255(setq org-export-odt-category-strings
11256 '(("en" "Table" "Illustration" "Equation" "Equation")))
11257@end lisp
11165 11258
11166You can turn off fontification support for literal examples by customizing 11259With this, previous image will be captioned as below in the exported
11167the variable @code{org-export-odt-fontify-srcblocks}. 11260document.
11168 11261
11262@example
11263Illustration 2: Bell curve
11264@end example
11265
11266@node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export
11267@subsection Literal examples in ODT export
11169 11268
11170@node Advanced topics in @acronym{ODT} export, , Literal examples in @acronym{ODT} export, OpenDocument Text export 11269Export of literal examples (@pxref{Literal examples}) with full fontification
11171@subsection Advanced topics in @acronym{ODT} export 11270is supported. Internally, the exporter relies on @file{htmlfontify.el} to
11271generate all style definitions needed for a fancy listing.@footnote{Your
11272@file{htmlfontify.el} library must atleast be at Emacs 24.1 levels for
11273fontification to be turned on.} The auto-generated styles have @samp{OrgSrc}
11274as prefix and inherit their color from the faces used by Emacs
11275@code{font-lock} library for the source language.
11172 11276
11173If you rely heavily on @acronym{ODT} export, you may want to exploit the full 11277@vindex org-export-odt-fontify-srcblocks
11278If you prefer to use your own custom styles for fontification, you can do so
11279by customizing the variable
11280@code{org-export-odt-create-custom-styles-for-srcblocks}.
11281
11282@vindex org-export-odt-create-custom-styles-for-srcblocks
11283You can turn off fontification of literal examples by customizing the
11284variable @code{org-export-odt-fontify-srcblocks}.
11285
11286@node Advanced topics in ODT export, , Literal examples in ODT export, OpenDocument Text export
11287@subsection Advanced topics in ODT export
11288
11289If you rely heavily on ODT export, you may want to exploit the full
11174set of features that the exporter offers. This section describes features 11290set of features that the exporter offers. This section describes features
11175that would be of interest to power users. 11291that would be of interest to power users.
11176 11292
11177@menu 11293@menu
11178* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats 11294* Configuring a document converter:: How to register a document converter
11179* Working with OpenDocument style files:: Explore the internals 11295* Working with OpenDocument style files:: Explore the internals
11180* Creating one-off styles:: How to produce custom highlighting etc 11296* Creating one-off styles:: How to produce custom highlighting etc
11181* Customizing tables in @acronym{ODT} export:: How to define and use Table templates 11297* Customizing tables in ODT export:: How to define and use Table templates
11182* Validating OpenDocument XML:: How to debug corrupt OpenDocument files 11298* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
11183@end menu 11299@end menu
11184 11300
11185@node Exporting and converting to other formats, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export, Advanced topics in @acronym{ODT} export 11301@node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export
11186@subsubsection Exporting and converting to other formats 11302@subsubsection Configuring a document converter
11187@cindex convert 11303@cindex convert
11188@cindex doc, docx 11304@cindex doc, docx, rtf
11189
11190The @acronym{ODT} exporter adds support for exporting Org outlines to formats
11191that are not supported natively by Org. It also adds support to convert
11192document from one format to another. To use these features, you need to
11193configure a command-line converter. Once a command-line converter is
11194configured you can use it to extend the list of formats to which Org can
11195export. @xref{x-export-to-other-formats,,Automatically exporting to other
11196formats}. You can also use it to perform one-off document conversion as
11197detailed below.
11198
11199@vindex org-export-odt-convert
11200@table @kbd
11201
11202@item M-x org-export-odt-convert
11203Convert an existing document from one format to another as determined by the
11204variable @code{org-export-odt-convert-capabilities}
11205(@pxref{x-odt-converter-capabilities,,Configure converter
11206capabilities}). @strong{Please note} that you can use this command to even
11207convert documents that are produced outside of Org and in other formats than
11208@acronym{ODT} format.
11209@end table
11210
11211@subsubheading Pre-configured converters
11212
11213@cindex converter 11305@cindex converter
11214The @acronym{ODT} exporter supports two converters out of the box:
11215
11216@enumerate
11217
11218@cindex @file{unoconv}
11219@item @file{unoconv}
11220
11221This converter is available as an installable package in your favorite
11222distribution.
11223
11224@cindex @file{BasicODConverter}
11225@item @file{BasicODConverter}
11226 11306
11227@vindex org-odt-data-dir 11307The ODT exporter can work with popular converters with little or no
11228This converter is distributed as a LibreOffice extension and can be found in 11308extra configuration from your side. @xref{Extending ODT export}.
11229your Org distribution. See the subdirectory pointed to by the variable 11309If you are using a converter that is not supported by default or if you would
11230@code{org-odt-data-dir}. 11310like to tweak the default converter settings, proceed as below.
11231
11232@end enumerate
11233
11234@subsubheading Installing a new converter
11235If you prefer to use a converter other than the two mentioned above, then you
11236may have to do additional configuration. You can proceed as follows:
11237 11311
11238@enumerate 11312@enumerate
11239@item Register the converter 11313@item Register the converter
@@ -11262,12 +11336,12 @@ Select the newly added converter as the preferred one by customizing the
11262variable @code{org-export-odt-convert-process}. 11336variable @code{org-export-odt-convert-process}.
11263@end enumerate 11337@end enumerate
11264 11338
11265@node Working with OpenDocument style files, Creating one-off styles, Exporting and converting to other formats, Advanced topics in @acronym{ODT} export 11339@node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export
11266@subsubsection Working with OpenDocument style files 11340@subsubsection Working with OpenDocument style files
11267@cindex styles, custom 11341@cindex styles, custom
11268@cindex template, custom 11342@cindex template, custom
11269 11343
11270This section explores the internals of the @acronym{ODT} exporter and the 11344This section explores the internals of the ODT exporter and the
11271means by which it produces styled documents. Read this section if you are 11345means by which it produces styled documents. Read this section if you are
11272interested in exploring the automatic and custom OpenDocument styles used by 11346interested in exploring the automatic and custom OpenDocument styles used by
11273the exporter. 11347the exporter.
@@ -11275,7 +11349,7 @@ the exporter.
11275@anchor{x-factory-styles} 11349@anchor{x-factory-styles}
11276@subsubheading Factory styles 11350@subsubheading Factory styles
11277 11351
11278The @acronym{ODT} exporter relies on two files for generating its output. 11352The ODT exporter relies on two files for generating its output.
11279These files are bundled with the distribution under the directory pointed to 11353These files are bundled with the distribution under the directory pointed to
11280by the variable @code{org-odt-styles-dir}. The two files are: 11354by the variable @code{org-odt-styles-dir}. The two files are:
11281 11355
@@ -11321,7 +11395,7 @@ are numbered.
11321 11395
11322@anchor{x-overriding-factory-styles} 11396@anchor{x-overriding-factory-styles}
11323@subsubheading Overriding factory styles 11397@subsubheading Overriding factory styles
11324The following two variables control the location from which the @acronym{ODT} 11398The following two variables control the location from which the ODT
11325exporter picks up the custom styles and content template files. You can 11399exporter picks up the custom styles and content template files. You can
11326customize these variables to override the factory styles used by the 11400customize these variables to override the factory styles used by the
11327exporter. 11401exporter.
@@ -11366,7 +11440,7 @@ Use this variable to specify the blank @file{content.xml} that will be used
11366in the final output. 11440in the final output.
11367@end itemize 11441@end itemize
11368 11442
11369@node Creating one-off styles, Customizing tables in @acronym{ODT} export, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export 11443@node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export
11370@subsubsection Creating one-off styles 11444@subsubsection Creating one-off styles
11371 11445
11372There are times when you would want one-off formatting in the exported 11446There are times when you would want one-off formatting in the exported
@@ -11433,14 +11507,14 @@ This paragraph is specially formatted and uses bold text.
11433 11507
11434@end enumerate 11508@end enumerate
11435 11509
11436@node Customizing tables in @acronym{ODT} export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in @acronym{ODT} export 11510@node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export
11437@subsubsection Customizing tables in @acronym{ODT} export 11511@subsubsection Customizing tables in ODT export
11438@cindex tables, in ODT export 11512@cindex tables, in ODT export
11439 11513
11440@cindex #+ATTR_ODT 11514@cindex #+ATTR_ODT
11441You can override the default formatting of the table by specifying a custom 11515You can override the default formatting of the table by specifying a custom
11442table style with the @code{#+ATTR_ODT} line. For a discussion on default 11516table style with the @code{#+ATTR_ODT} line. For a discussion on default
11443formatting of tables @pxref{Tables in @acronym{ODT} export}. 11517formatting of tables @pxref{Tables in ODT export}.
11444 11518
11445This feature closely mimics the way table templates are defined in the 11519This feature closely mimics the way table templates are defined in the
11446OpenDocument-v1.2 11520OpenDocument-v1.2
@@ -11466,7 +11540,7 @@ the table that follows.
11466@end lisp 11540@end lisp
11467 11541
11468@example 11542@example
11469#+ATTR_ODT: TableWithHeaderRowAndColumn 11543#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
11470| Name | Phone | Age | 11544| Name | Phone | Age |
11471| Peter | 1234 | 17 | 11545| Peter | 1234 | 17 |
11472| Anna | 4321 | 25 | 11546| Anna | 4321 | 25 |
@@ -11571,9 +11645,9 @@ To define a table style, create an entry for the style in the variable
11571@end itemize 11645@end itemize
11572 11646
11573For example, the entry below defines two different table styles 11647For example, the entry below defines two different table styles
11574@samp{TableWithHeaderRowsAndColumns} and @samp{TableWithHeaderColumns} based 11648@samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
11575on the same template @samp{Custom}. The styles achieve their intended effect 11649based on the same template @samp{Custom}. The styles achieve their intended
11576by selectively activating the individual cell styles in that template. 11650effect by selectively activating the individual cell styles in that template.
11577 11651
11578@lisp 11652@lisp
11579(setq org-export-odt-table-styles 11653(setq org-export-odt-table-styles
@@ -11593,18 +11667,18 @@ To do this, specify the table style created in step (2) as part of
11593the @code{ATTR_ODT} line as shown below. 11667the @code{ATTR_ODT} line as shown below.
11594 11668
11595@example 11669@example
11596#+ATTR_ODT: TableWithHeaderRowAndColumn 11670#+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
11597| Name | Phone | Age | 11671| Name | Phone | Age |
11598| Peter | 1234 | 17 | 11672| Peter | 1234 | 17 |
11599| Anna | 4321 | 25 | 11673| Anna | 4321 | 25 |
11600@end example 11674@end example
11601@end enumerate 11675@end enumerate
11602 11676
11603@node Validating OpenDocument XML, , Customizing tables in @acronym{ODT} export, Advanced topics in @acronym{ODT} export 11677@node Validating OpenDocument XML, , Customizing tables in ODT export, Advanced topics in ODT export
11604@subsubsection Validating OpenDocument XML 11678@subsubsection Validating OpenDocument XML
11605 11679
11606Occasionally, you will discover that the document created by the 11680Occasionally, you will discover that the document created by the
11607@acronym{ODT} exporter cannot be opened by your favorite application. One of 11681ODT exporter cannot be opened by your favorite application. One of
11608the common reasons for this is that the @file{.odt} file is corrupt. In such 11682the common reasons for this is that the @file{.odt} file is corrupt. In such
11609cases, you may want to validate the document against the OpenDocument RELAX 11683cases, you may want to validate the document against the OpenDocument RELAX
11610NG Compact Syntax (RNC) schema. 11684NG Compact Syntax (RNC) schema.
@@ -11618,7 +11692,7 @@ general help with validation (and schema-sensitive editing) of XML files:
11618If you have ready access to OpenDocument @file{.rnc} files and the needed 11692If you have ready access to OpenDocument @file{.rnc} files and the needed
11619schema-locating rules in a single folder, you can customize the variable 11693schema-locating rules in a single folder, you can customize the variable
11620@code{org-export-odt-schema-dir} to point to that directory. The 11694@code{org-export-odt-schema-dir} to point to that directory. The
11621@acronym{ODT} exporter will take care of updating the 11695ODT exporter will take care of updating the
11622@code{rng-schema-locating-files} for you. 11696@code{rng-schema-locating-files} for you.
11623 11697
11624@c end opendocument 11698@c end opendocument
@@ -12622,17 +12696,24 @@ of tangled code files.
12622@section Evaluating code blocks 12696@section Evaluating code blocks
12623@cindex code block, evaluating 12697@cindex code block, evaluating
12624@cindex source code, evaluating 12698@cindex source code, evaluating
12699@cindex #+RESULTS
12625 12700
12626Code blocks can be evaluated@footnote{Whenever code is evaluated there is a 12701Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
12627potential for that code to do harm. Org mode provides safeguards to ensure 12702potential for that code to do harm. Org mode provides safeguards to ensure
12628that code is only evaluated after explicit confirmation from the user. For 12703that code is only evaluated after explicit confirmation from the user. For
12629information on these safeguards (and on how to disable them) see @ref{Code 12704information on these safeguards (and on how to disable them) see @ref{Code
12630evaluation security}.} and the results of evaluation optionally placed in the 12705evaluation security}.} and the results of evaluation optionally placed in the
12631Org mode buffer. By default, the evaluation facility is only enabled for 12706Org mode buffer. The results of evaluation are placed following a line that
12632Lisp code blocks specified as @code{emacs-lisp}. However, source code blocks 12707begins by default with @code{#+RESULTS} and optionally a cache identifier
12633in many languages can be evaluated within Org mode (see @ref{Languages} for a 12708and/or the name of the evaluated code block. The default value of
12634list of supported languages and @ref{Structure of code blocks} for 12709@code{#+RESULTS} can be changed with the customizable variable
12635information on the syntax used to define a code block). 12710@code{org-babel-results-keyword}.
12711
12712By default, the evaluation facility is only enabled for Lisp code blocks
12713specified as @code{emacs-lisp}. However, source code blocks in many languages
12714can be evaluated within Org mode (see @ref{Languages} for a list of supported
12715languages and @ref{Structure of code blocks} for information on the syntax
12716used to define a code block).
12636 12717
12637@kindex C-c C-c 12718@kindex C-c C-c
12638There are a number of ways to evaluate code blocks. The simplest is to press 12719There are a number of ways to evaluate code blocks. The simplest is to press
@@ -13000,6 +13081,7 @@ argument in lowercase letters. The following header arguments are defined:
13000* session:: Preserve the state of code evaluation 13081* session:: Preserve the state of code evaluation
13001* noweb:: Toggle expansion of noweb references 13082* noweb:: Toggle expansion of noweb references
13002* noweb-ref:: Specify block's noweb reference resolution target 13083* noweb-ref:: Specify block's noweb reference resolution target
13084* noweb-sep:: String used to separate noweb references
13003* cache:: Avoid re-evaluating unchanged code blocks 13085* cache:: Avoid re-evaluating unchanged code blocks
13004* sep:: Delimiter for writing tabular results outside Org 13086* sep:: Delimiter for writing tabular results outside Org
13005* hlines:: Handle horizontal lines in tables 13087* hlines:: Handle horizontal lines in tables
@@ -13351,9 +13433,9 @@ The result is converted to pretty-printed code and is enclosed in a code
13351block. This option currently supports Emacs Lisp, Python, and Ruby. E.g., 13433block. This option currently supports Emacs Lisp, Python, and Ruby. E.g.,
13352@code{:results value pp}. 13434@code{:results value pp}.
13353@item @code{wrap} 13435@item @code{wrap}
13354The result is wrapped in a @code{begin_result} block. This can be useful for 13436The result is wrapped in a RESULTS drawer. This can be useful for
13355inserting @code{raw} or @code{org} syntax results in such a way that their 13437inserting @code{raw} or @code{org} syntax results in such a way that their
13356extend is known and they can be automatically removed or replaced. 13438extent is known and they can be automatically removed or replaced.
13357@end itemize 13439@end itemize
13358 13440
13359@subsubheading Handling 13441@subsubheading Handling
@@ -13583,9 +13665,8 @@ argument can have one of three values: @code{yes}, @code{no}, or @code{tangle}.
13583All ``noweb'' syntax references in the body of the code block will be 13665All ``noweb'' syntax references in the body of the code block will be
13584expanded before the block is evaluated, tangled or exported. 13666expanded before the block is evaluated, tangled or exported.
13585@item @code{no} 13667@item @code{no}
13586The default. No ``noweb'' syntax specific action is taken on evaluating 13668The default. No ``noweb'' syntax specific action is taken when the code
13587code blocks, However, noweb references will still be expanded during 13669block is evaluated, tangled or exported.
13588tangling.
13589@item @code{tangle} 13670@item @code{tangle}
13590All ``noweb'' syntax references in the body of the code block will be 13671All ``noweb'' syntax references in the body of the code block will be
13591expanded before the block is tangled, however ``noweb'' references will not 13672expanded before the block is tangled, however ``noweb'' references will not
@@ -13617,7 +13698,7 @@ Note that noweb replacement text that does not contain any newlines will not
13617be affected by this change, so it is still possible to use inline noweb 13698be affected by this change, so it is still possible to use inline noweb
13618references. 13699references.
13619 13700
13620@node noweb-ref, cache, noweb, Specific header arguments 13701@node noweb-ref, noweb-sep, noweb, Specific header arguments
13621@subsubsection @code{:noweb-ref} 13702@subsubsection @code{:noweb-ref}
13622When expanding ``noweb'' style references the bodies of all code block with 13703When expanding ``noweb'' style references the bodies of all code block with
13623@emph{either} a block name matching the reference name @emph{or} a 13704@emph{either} a block name matching the reference name @emph{or} a
@@ -13661,13 +13742,27 @@ inheritance}).}.
13661 #+END_SRC 13742 #+END_SRC
13662@end example 13743@end example
13663 13744
13664@node cache, sep, noweb-ref, Specific header arguments 13745The @code{:noweb-sep} (see @ref{noweb-sep}) header argument holds the string
13746used to separate accumulate noweb references like those above. By default a
13747newline is used.
13748
13749@node noweb-sep, cache, noweb-ref, Specific header arguments
13750@subsubsection @code{:noweb-sep}
13751
13752The @code{:noweb-sep} header argument holds the string used to separate
13753accumulate noweb references (see @ref{noweb-ref}). By default a newline is
13754used.
13755
13756@node cache, sep, noweb-sep, Specific header arguments
13665@subsubsection @code{:cache} 13757@subsubsection @code{:cache}
13666 13758
13667The @code{:cache} header argument controls the use of in-buffer caching of 13759The @code{:cache} header argument controls the use of in-buffer caching of
13668the results of evaluating code blocks. It can be used to avoid re-evaluating 13760the results of evaluating code blocks. It can be used to avoid re-evaluating
13669unchanged code blocks. This header argument can have one of two 13761unchanged code blocks. Note that the @code{:cache} header argument will not
13670values: @code{yes} or @code{no}. 13762attempt to cache results when the @code{:session} header argument is used,
13763because the results of the code block execution may be stored in the session
13764outside of the Org-mode buffer. The @code{:cache} header argument can have
13765one of two values: @code{yes} or @code{no}.
13671 13766
13672@itemize @bullet 13767@itemize @bullet
13673@item @code{no} 13768@item @code{no}
@@ -14004,6 +14099,14 @@ evaluation. If @code{:noweb no}, the default, then the reference is not
14004expanded before evaluation. See the @ref{noweb-ref} header argument for 14099expanded before evaluation. See the @ref{noweb-ref} header argument for
14005a more flexible way to resolve noweb references. 14100a more flexible way to resolve noweb references.
14006 14101
14102It is possible to include the @emph{results} of a code block rather than the
14103body. This is done by appending parenthesis to the code block name which may
14104optionally contain arguments to the code block as shown below.
14105
14106@example
14107<<code-block-name(optional arguments)>>
14108@end example
14109
14007Note: the default value, @code{:noweb no}, was chosen to ensure that 14110Note: the default value, @code{:noweb no}, was chosen to ensure that
14008correct code is not broken in a language, such as Ruby, where 14111correct code is not broken in a language, such as Ruby, where
14009@code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is not 14112@code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is not
@@ -14040,34 +14143,72 @@ are active:
14040In an Org mode buffer, the following key bindings are active: 14143In an Org mode buffer, the following key bindings are active:
14041 14144
14042@multitable @columnfractions 0.45 0.55 14145@multitable @columnfractions 0.45 0.55
14043@kindex C-c C-v a 14146@kindex C-c C-v p
14044@kindex C-c C-v C-a 14147@kindex C-c C-v C-p
14045@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash} 14148@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
14149@kindex C-c C-v n
14150@kindex C-c C-v C-n
14151@item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
14152@kindex C-c C-v e
14153@kindex C-c C-v C-e
14154@item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
14155@kindex C-c C-v o
14156@kindex C-c C-v C-o
14157@item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
14158@kindex C-c C-v v
14159@kindex C-c C-v C-v
14160@item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
14161@kindex C-c C-v u
14162@kindex C-c C-v C-u
14163@item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
14164@kindex C-c C-v g
14165@kindex C-c C-v C-g
14166@item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
14167@kindex C-c C-v r
14168@kindex C-c C-v C-r
14169@item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
14046@kindex C-c C-v b 14170@kindex C-c C-v b
14047@kindex C-c C-v C-b 14171@kindex C-c C-v C-b
14048@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer} 14172@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
14049@kindex C-c C-v f
14050@kindex C-c C-v C-f
14051@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
14052@kindex C-c C-v g
14053@item @kbd{C-c C-v g} @tab @code{org-babel-goto-named-source-block}
14054@kindex C-c C-v h
14055@item @kbd{C-c C-v h} @tab @code{org-babel-describe-bindings}
14056@kindex C-c C-v l
14057@kindex C-c C-v C-l
14058@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
14059@kindex C-c C-v p
14060@kindex C-c C-v C-p
14061@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
14062@kindex C-c C-v s 14173@kindex C-c C-v s
14063@kindex C-c C-v C-s 14174@kindex C-c C-v C-s
14064@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree} 14175@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
14176@kindex C-c C-v d
14177@kindex C-c C-v C-d
14178@item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
14065@kindex C-c C-v t 14179@kindex C-c C-v t
14066@kindex C-c C-v C-t 14180@kindex C-c C-v C-t
14067@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle} 14181@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
14182@kindex C-c C-v f
14183@kindex C-c C-v C-f
14184@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
14185@kindex C-c C-v c
14186@kindex C-c C-v C-c
14187@item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
14188@kindex C-c C-v j
14189@kindex C-c C-v C-j
14190@item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
14191@kindex C-c C-v l
14192@kindex C-c C-v C-l
14193@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
14194@kindex C-c C-v i
14195@kindex C-c C-v C-i
14196@item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
14197@kindex C-c C-v I
14198@kindex C-c C-v C-I
14199@item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
14068@kindex C-c C-v z 14200@kindex C-c C-v z
14069@kindex C-c C-v C-z 14201@kindex C-c C-v C-z
14070@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session} 14202@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session-with-code}
14203@kindex C-c C-v a
14204@kindex C-c C-v C-a
14205@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
14206@kindex C-c C-v h
14207@kindex C-c C-v C-h
14208@item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
14209@kindex C-c C-v x
14210@kindex C-c C-v C-x
14211@item @kbd{C-c C-v x} @ @ @r{or} @ @ @kbd{C-c C-v C-x} @tab @code{org-babel-do-key-sequence-in-edit-buffer}
14071@end multitable 14212@end multitable
14072 14213
14073@c When possible these keybindings were extended to work when the control key is 14214@c When possible these keybindings were extended to work when the control key is
@@ -14839,7 +14980,7 @@ checks for the availability of Calc by looking for the function
14839been installed properly. As of Emacs 22, Calc is part of the Emacs 14980been installed properly. As of Emacs 22, Calc is part of the Emacs
14840distribution. Another possibility for interaction between the two 14981distribution. Another possibility for interaction between the two
14841packages is using Calc for embedded calculations. @xref{Embedded Mode, 14982packages is using Calc for embedded calculations. @xref{Embedded Mode,
14842, Embedded Mode, Calc, GNU Emacs Calc Manual}. 14983, Embedded Mode, calc, GNU Emacs Calc Manual}.
14843@item @file{constants.el} by Carsten Dominik 14984@item @file{constants.el} by Carsten Dominik
14844@cindex @file{constants.el} 14985@cindex @file{constants.el}
14845@cindex Dominik, Carsten 14986@cindex Dominik, Carsten
@@ -15215,7 +15356,7 @@ not accept any arguments, and return the full link with prefix.
15215@vindex org-ctrl-c-ctrl-c-hook 15356@vindex org-ctrl-c-ctrl-c-hook
15216 15357
15217Org has several commands that act differently depending on context. The most 15358Org has several commands that act differently depending on context. The most
15218important example it the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}). 15359important example is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
15219Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property. 15360Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.
15220 15361
15221Add-ons can tap into this functionality by providing a function that detects 15362Add-ons can tap into this functionality by providing a function that detects
@@ -16431,7 +16572,7 @@ with links transformation to Org syntax.
16431@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual 16572@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
16432chapter about publishing. 16573chapter about publishing.
16433@item 16574@item
16434@i{Jambunathan K} contributed the @acronym{ODT} exporter. 16575@i{Jambunathan K} contributed the ODT exporter.
16435@item 16576@item
16436@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and 16577@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
16437enabled source code highlighting in Gnus. 16578enabled source code highlighting in Gnus.