@c %**start of header
@setfilename ../../info/org
@settitle The Org Manual
-
-@include org-version.inc
+@set VERSION 8.2.5c
@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@set MAINTAINER Carsten Dominik
@set MAINTAINEREMAIL @email{carsten at orgmode dot org}
@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
+@documentencoding UTF-8
@c %**end of header
@finalout
@copying
This manual is for Org version @value{VERSION}.
-Copyright @copyright{} 2004--2013 Free Software Foundation, Inc.
+Copyright @copyright{} 2004--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@dircategory Emacs editing modes
@direntry
-* Org Mode: (org). Outline-based notes management and organizer
+* Org Mode: (org). Outline-based notes management and organizer.
@end direntry
@titlepage
* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
* Markdown export:: Exporting to Markdown
* OpenDocument Text export:: Exporting to OpenDocument Text
+* Org export:: Exporting to Org
* iCalendar export:: Exporting to iCalendar
* Other built-in back-ends:: Exporting to @code{Texinfo}, a man page, or Org
* Export in foreign buffers:: Author tables in lists in Org syntax
* System-wide header arguments:: Set global default values
* Language-specific header arguments:: Set default values by language
* Header arguments in Org mode properties:: Set default values for a buffer or heading
-* Language-specific header arguments in Org mode properties:: Set langugage-specific default values for a buffer or heading
+* Language-specific header arguments in Org mode properties:: Set language-specific default values for a buffer or heading
* Code block specific header arguments:: The most common way to set values
* Header arguments in function calls:: The most specific level
CONTENTS view up to headlines of level N will be shown. Note that inside
tables, @kbd{S-@key{TAB}} jumps to the previous field.
+@cindex set startup visibility, command
+@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
+Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
@cindex show all, command
@orgcmd{C-u C-u C-u @key{TAB},show-all}
Show all, including drawers.
Search for a link target @samp{<<My Target>>}, or do a text search for
@samp{my target}, similar to the search in internal links, see
@ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
-link will become a HTML reference to the corresponding named anchor in
+link will become an HTML reference to the corresponding named anchor in
the linked file.
@item *My Target
In an Org file, restrict search to headlines.
time as matching tags. The properties may be real properties, or special
properties that represent other metadata (@pxref{Special properties}). For
example, the ``property'' @code{TODO} represents the TODO keyword of the
-entry and the ``propety'' @code{PRIORITY} represents the PRIORITY keyword of
+entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
the entry. The ITEM special property cannot currently be used in tags/property
searches@footnote{But @pxref{x-agenda-skip-entry-regexp,
,skipping entries based on regexp}.}.
@end table
When set to a positive integer, each option will exclude entries from other
-catogories: for example, @code{(setq org-agenda-max-effort 100)} will limit
+categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
the agenda to 100 minutes of effort and exclude any entry that as no effort
property. If you want to include entries with no effort property, use a
negative value for @code{org-agenda-max-effort}.
@end example
If you would like to move the table of contents to a different location, you
-should turn off the detault table using @code{org-export-with-toc} or
+should turn off the default table using @code{org-export-with-toc} or
@code{#+OPTIONS} and insert @code{#+TOC: headlines N} at the desired
location(s).
Contents of the included file will belong to the same structure (headline,
item) containing the @code{INCLUDE} keyword. In particular, headlines within
-the file will become children of the current section. That behaviour can be
+the file will become children of the current section. That behavior can be
changed by providing an additional keyword parameter, @code{:minlevel}. In
that case, all headlines in the included file will be shifted so the one with
the lowest level reaches that specified level. For example, to make a file
examples}). It is also possible to create blocks containing raw code
targeted at a specific back-ends (e.g., @samp{#+BEGIN_LATEX}).
-Any other block is a @emph{special block}. Each export back-end decides if
-they should be exported, and how. When the block is ignored, its contents
-are still exported, as if the block were not there. For example, when
-exporting a @samp{#+BEGIN_TEST} block, HTML back-end wraps its contents
-within @samp{<div name="test">} tag. Refer to back-end specific
-documentation for more information.
+Any other block is a @emph{special block}.
+
+For example, @samp{#+BEGIN_ABSTRACT} and @samp{#+BEGIN_VIDEO} are special
+blocks. The first one is useful when exporting to @LaTeX{}, the second one
+when exporting to HTML5.
+
+Each export back-end decides if they should be exported, and how. When the
+block is ignored, its contents are still exported, as if the opening and
+closing block lines were not there. For example, when exporting a
+@samp{#+BEGIN_TEST} block, HTML back-end wraps its contents within a
+@samp{<div name="test">} tag.
+
+Refer to back-end specific documentation for more information.
@node Exporting, Publishing, Markup, Top
@chapter Exporting
* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
* Markdown export:: Exporting to Markdown
* OpenDocument Text export:: Exporting to OpenDocument Text
+* Org export:: Exporting to Org
* iCalendar export:: Exporting to iCalendar
* Other built-in back-ends:: Exporting to @code{Texinfo}, a man page, or Org
* Export in foreign buffers:: Author tables in lists in Org syntax
argument, or with @kbd{&} key from the dispatcher.
@vindex org-export-in-background
-To make this behaviour the default, customize the variable
+To make this behavior the default, customize the variable
@code{org-export-in-background}.
@item C-b
@item man (Man page format)
@item md (Markdown format)
@item odt (OpenDocument Text format)
+@item org (Org format)
@item texinfo (Texinfo format)
@end itemize
The tags that select a tree for export (@code{org-export-select-tags}). The
default value is @code{:export:}. Within a subtree tagged with
@code{:export:}, you can still exclude entries with @code{:noexport:} (see
-below).
+below). When headlines are selectively exported with @code{:export:}
+anywhere in a file, text before the first headline is ignored.
@item EXCLUDE_TAGS
The tags that exclude a tree from export (@code{org-export-exclude-tags}).
@cindex property, EXPORT_FILE_NAME
When exporting only a subtree, each of the previous keywords@footnote{With
-the exception of @samp{SETUPFILE}.} can be overriden locally by special node
+the exception of @samp{SETUPFILE}.} can be overridden locally by special node
properties. These begin with @samp{EXPORT_}, followed by the name of the
keyword they supplant. For example, @samp{DATE} and @samp{OPTIONS} keywords
become, respectively, @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}
@cindex #+BEAMER_INNER_THEME
@cindex #+BEAMER_OUTER_THEME
Beamer export introduces a number of keywords to insert code in the
-document's header. Four control appearance of the presentantion:
+document's header. Four control appearance of the presentation:
@code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
@code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
@code{#+BEAMER_OUTER_THEME}. All of them accept optional arguments
@section HTML export
@cindex HTML export
-Org mode contains a HTML (XHTML 1.0 strict) exporter with extensive
+Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
HTML formatting, in ways similar to John Gruber's @emph{markdown}
language, but with additional support for tables.
@table @kbd
@orgcmd{C-c C-e h h,org-html-export-to-html}
-Export as a HTML file. For an Org file @file{myfile.org},
+Export as an HTML file. For an Org file @file{myfile.org},
the HTML file will be @file{myfile.html}. The file will be overwritten
without warning.
@kbd{C-c C-e h o}
-Export as a HTML file and immediately open it with a browser.
+Export as an HTML file and immediately open it with a browser.
@orgcmd{C-c C-e h H,org-html-export-as-html}
Export to a temporary buffer. Do not create a file.
@end table
Org can export to various (X)HTML flavors.
Setting the variable @code{org-html-doctype} allows you to export to different
-(X)HTML variants. The exported HTML will be adjusted according to the sytax
+(X)HTML variants. The exported HTML will be adjusted according to the syntax
requirements of that variant. You can either set this variable to a doctype
string directly, in which case the exporter will try to adjust the syntax
automatically, or you can use a ready-made doctype. The ready-made options
@end example
Special blocks that do not correspond to HTML5 elements (see
-@code{org-html-html5-elements}) will revert to the usual behavior,
-i.e. #+BEGIN_LEDERHOSEN will still export to <div class=''lederhosen''>.
+@code{org-html-html5-elements}) will revert to the usual behavior, i.e.,
+@code{#+BEGIN_LEDERHOSEN} will still export to @samp{<div class="lederhosen">}.
Headlines cannot appear within special blocks. To wrap a headline and its
-contents in e.g. <section> or <article> tags, set the @code{HTML_CONTAINER}
-property on the headline itself.
+contents in e.g., @samp{<section>} or @samp{<article>} tags, set the
+@code{HTML_CONTAINER} property on the headline itself.
@node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export
@subsection HTML preamble and postamble
targets}). Links to external files will still work if the target file is on
the same @i{relative} path as the published Org file. Links to other
@file{.org} files will be translated into HTML links under the assumption
-that a HTML version also exists of the linked file, at the same relative
+that an HTML version also exists of the linked file, at the same relative
path. @samp{id:} links can then be used to jump to specific entries across
files. For information related to linking files while publishing them to a
publishing directory see @ref{Publishing links}.
@code{t}: if you want to make the source block a float. It is the default
value when a caption is provided.
@item
-@code{mulicolumn}: if you wish to include a source block which spans multiple
-colums in a page.
+@code{multicolumn}: if you wish to include a source block which spans multiple
+columns in a page.
@item
-@code{nil}: if you need to avoid any floating evironment, even when a caption
+@code{nil}: if you need to avoid any floating environment, even when a caption
is provided. It is useful for source code that may not fit in a single page.
@end itemize
@subsubheading Special blocks in @LaTeX{} export
@cindex special blocks, in @LaTeX{} export
+@cindex abstract, in @LaTeX{} export
+@cindex proof, in @LaTeX{} export
In @LaTeX{} back-end, special blocks become environments of the same name.
Value of @code{:options} attribute will be appended as-is to that
environment's opening string. For example:
@example
+#+BEGIN_ABSTRACT
+We demonstrate how to solve the Syracuse problem.
+#+END_ABSTRACT
+
#+ATTR_LATEX: :options [Proof of important theorem]
#+BEGIN_PROOF
...
becomes
@example
+\begin@{abstract@}
+We demonstrate how to solve the Syracuse problem.
+\end@{abstract@}
+
\begin@{proof@}[Proof of important theorem]
...
Therefore, any even number greater than 2 is the sum of two primes.
@section Markdown export
@cindex Markdown export
-@code{md} export back-end generates Markdown syntax@footnote{Vanilla flavour,
+@code{md} export back-end generates Markdown syntax@footnote{Vanilla flavor,
as defined at @url{http://daringfireball.net/projects/markdown/}.} for an Org
mode buffer.
@c begin opendocument
-@node OpenDocument Text export, iCalendar export, Markdown export, Exporting
+@node OpenDocument Text export, Org export, Markdown export, Exporting
@section OpenDocument Text export
@cindex ODT
@cindex OpenDocument
@enumerate
@item Embedding ODT tags as part of regular text
-You can include simple OpenDocument tags by prefixing them with
-@samp{@@}. For example, to highlight a region of text do the following:
+You can inline OpenDocument syntax by enclosing it within
+@samp{@@@@odt:...@@@@} markup. For example, to highlight a region of text do
+the following:
@example
-@@<text:span text:style-name="Highlight">This is a
-highlighted text@@</text:span>. But this is a
-regular text.
+@@@@odt:<text:span text:style-name="Highlight">This is a highlighted
+text</text:span>@@@@. But this is a regular text.
@end example
@strong{Hint:} To see the above example in action, edit your
@c end opendocument
-@node iCalendar export, Other built-in back-ends, OpenDocument Text export, Exporting
+@node Org export
+@section Org export
+@cindex Org export
+
+@code{org} export back-end creates a normalized version of the Org document
+in current buffer. In particular, it evaluates Babel code (@pxref{Evaluating
+code blocks}) and removes other back-ends specific contents.
+
+@subheading Org export commands
+
+@table @kbd
+@orgcmd{C-c C-e O o,org-org-export-to-org}
+Export as an Org document. For an Org file, @file{myfile.org}, the resulting
+file will be @file{myfile.org.org}. The file will be overwritten without
+warning.
+@orgcmd{C-c C-e O O,org-org-export-as-org}
+Export to a temporary buffer. Do not create a file.
+@item C-c C-e O v
+Export to an Org file, then open it.
+@end table
+
+@node iCalendar export, Other built-in back-ends, Org export, Exporting
@section iCalendar export
@cindex iCalendar export
@cindex export back-ends, built-in
@vindex org-export-backends
-On top of the aforemetioned back-ends, Org comes with other built-in ones:
+On top of the aforementioned back-ends, Org comes with other built-in ones:
@itemize
@item @file{ox-man.el}: export to a man page.
@item @file{ox-texinfo.el}: export to @code{Texinfo} format.
-@item @file{ox-org.el}: export to an Org document.
@end itemize
To activate these export back-end, customize @code{org-export-backends} or
Convert the selected region into @code{MarkDown}.
@end table
-This is particularily useful for converting tables and lists in foreign
-buffers. E.g., in a HTML buffer, you can turn on @code{orgstruct-mode}, then
+This is particularly useful for converting tables and lists in foreign
+buffers. E.g., in an HTML buffer, you can turn on @code{orgstruct-mode}, then
use Org commands for editing a list, and finally select and convert the list
with @code{M-x org-html-convert-region-to-html RET}.
@end lisp
The @code{my-ascii-src-block} function looks at the attribute above the
-element. If it isn’t true, it gives hand to the @code{ascii} back-end.
+element. If it isn't true, it gives hand to the @code{ascii} back-end.
Otherwise, it creates a box around the code, leaving room for the language.
-A new back-end is then created. It only changes its behaviour when
+A new back-end is then created. It only changes its behavior when
translating @code{src-block} type element. Now, all it takes to use the new
back-end is calling the following from an Org buffer:
@end multitable
@vindex org-html-doctype
+@vindex org-html-container-element
+@vindex org-html-html5-fancy
@vindex org-html-xml-declaration
@vindex org-html-link-up
@vindex org-html-link-home
@vindex org-html-link-org-files-as-html
+@vindex org-html-link-use-abs-url
@vindex org-html-head
@vindex org-html-head-extra
@vindex org-html-inline-images
@vindex org-html-preamble
@vindex org-html-postamble
@vindex org-html-table-default-attributes
+@vindex org-html-table-row-tags
@vindex org-html-head-include-default-style
@vindex org-html-head-include-scripts
@multitable @columnfractions 0.32 0.68
@item @code{:html-doctype} @tab @code{org-html-doctype}
+@item @code{:html-container} @tab @code{org-html-container-element}
+@item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
@item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
@item @code{:html-link-up} @tab @code{org-html-link-up}
@item @code{:html-link-home} @tab @code{org-html-link-home}
@item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html}
+@item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
@item @code{:html-head} @tab @code{org-html-head}
@item @code{:html-head-extra} @tab @code{org-html-head-extra}
@item @code{:html-inline-images} @tab @code{org-html-inline-images}
@item @code{:html-extension} @tab @code{org-html-extension}
@item @code{:html-preamble} @tab @code{org-html-preamble}
@item @code{:html-postamble} @tab @code{org-html-postamble}
-@item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
+@item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
+@item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags}
@item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
@item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
@end multitable
can be useful in situations where potentially untrusted Org mode files are
exported in an automated fashion, for example when Org mode is used as the
markup language for a wiki. It is also possible to set this variable to
-@code{‘inline-only}. In that case, only inline code blocks will be
+@code{'inline-only}. In that case, only inline code blocks will be
evaluated, in order to insert their results. Non-inline code blocks are
assumed to have their results already inserted in the buffer by manual
evaluation. This setting is useful to avoid expensive recalculations during
outermost call or source block.@footnote{The deprecated syntax for default
header argument properties, using the name of the header argument as a
property name directly, evaluates the property as seen by the corresponding
-source block definition. This behaviour has been kept for backwards
+source block definition. This behavior has been kept for backwards
compatibility.}
In the following example the value of
@enumerate
@item
-Reduce the number of Org agenda files: this will reduce the slowliness caused
-by accessing to a hard drive.
+Reduce the number of Org agenda files: this will reduce the slowness caused
+by accessing a hard drive.
@item
Reduce the number of DONE and archived headlines: this way the agenda does
not need to skip them.
asked for a way to narrow wide table columns.
@item
@i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
-several years now. He also sponsered the hosting costs until Rackspace
+several years now. He also sponsored the hosting costs until Rackspace
started to host us for free.
@item
@i{Thomas S. Dye} contributed documentation on Worg and helped integrating