summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <n.goaziou@gmail.com>2013-04-09 14:53:03 +0200
committerBastien Guerry <bzg@altern.org>2013-04-09 15:24:58 +0200
commit1d6693c087ce5aa113e2e0b280188f42311fe24b (patch)
tree7cf64ff333362c3d8756213a853ec07768543795
parent4c426b003d730582ac8af77c6fc76d79b2eec1ce (diff)
downloadorg-mode-1d6693c087ce5aa113e2e0b280188f42311fe24b.tar.gz
doc/org.texi: Massive rewrite of the first sections
* doc/org.texi (Exporting): Massive rewrite of the first sections. (Selective export): Delete. (The Export Dispatcher): Rewrite. (Export options): Rewrite as "Export settings".
-rw-r--r--doc/org.texi493
1 files changed, 308 insertions, 185 deletions
diff --git a/doc/org.texi b/doc/org.texi
index 6531d22..654495e 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -576,9 +576,9 @@ Embedded @LaTeX{}
Exporting
-* Selective export:: Using tags to select and exclude trees
-* Export options:: Per-file export settings
-* The export dispatcher:: How to access exporter commands
+* The Export Dispatcher:: The main exporter interface
+* Export formats:: Available export formats
+* Export settings:: Generic export settings
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* HTML export:: Exporting to HTML
* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
@@ -9342,7 +9342,7 @@ markup rules used in an Org mode buffer.
@menu
* Structural markup elements:: The basic structure as seen by the exporter
-* Images and tables:: Tables and Images will be included
+* Images and tables:: Images, tables and caption mechanism
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
* Index entries:: Making an index
@@ -10087,24 +10087,21 @@ is normal.
@chapter Exporting
@cindex exporting
-Org mode documents can be exported into a variety of other formats. For
-printing and sharing notes, ASCII export produces a readable and simple
+Org mode documents can be exported into a variety of other formats.
+
+For printing and sharing notes, ASCII export produces a readable and simple
version of an Org file. HTML export allows you to publish a notes file on
the web. @LaTeX{} export lets you use Org mode and its structured editing
functions to easily create @LaTeX{} files. OpenDocument Text (ODT) export
allows seamless collaboration across organizational boundaries. To
incorporate entries with associated times like deadlines or appointments into
a desktop calendar program like iCal, Org mode can also produce extracts in
-the iCalendar format. Currently, Org mode only supports export, not import
-of these different formats.
-
-Org supports export of selected regions when @code{transient-mark-mode} is
-enabled (default in Emacs 23).
+the iCalendar format.
@menu
-* Selective export:: Using tags to select and exclude trees
-* Export options:: Per-file export settings
-* The export dispatcher:: How to access exporter commands
+* The Export Dispatcher:: The main exporter interface
+* Export formats:: Available export formats
+* Export settings:: Generic export settings
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* HTML export:: Exporting to HTML
* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
@@ -10112,187 +10109,315 @@ enabled (default in Emacs 23).
* iCalendar export:: Exporting in iCalendar format
@end menu
-@node Selective export, Export options, Exporting, Exporting
-@section Selective export
-@cindex export, selective by tags or TODO keyword
+@node The Export Dispatcher, Export formats, Exporting, Exporting
+@section The Export Dispatcher
+@vindex org-export-dispatch-use-expert-ui
+@cindex Export, dispatcher
+
+The main entry point for any export related task is the dispatcher, a
+hierarchical menu@footnote{It is also possible to use a less intrusive
+interface by setting @var{org-export-dispatch-use-expert-ui} to a non-nil
+value. In that case, only a prompt is visible from the minibuffer. From
+there one can still switch back to regular menu with @kbd{?} key.} from
+which it is possible to select an export format and to toggle export
+options.
-@vindex org-export-select-tags
-@vindex org-export-exclude-tags
-@cindex org-export-with-tasks
-You may use tags to select the parts of a document that should be exported,
-or to exclude parts from export. This behavior is governed by two variables:
-@code{org-export-select-tags} and @code{org-export-exclude-tags},
-respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}.
+@c @quotation
+@table @asis
+@orgcmd{C-c C-e,org-export-dispatch}
-@enumerate
-@item
-Org first checks if any of the @emph{select} tags is present in the
-buffer. If yes, all trees that do not carry one of these tags will be
-excluded. If a selected tree is a subtree, the heading hierarchy above it
-will also be selected for export, but not the text below those headings.
+Dispatch for export and publishing commands. When called with @kbd{C-u}
+prefix argument, repeat last command, preserving toggled options, on
+current buffer. If the active buffer hasn't changed and subtree export was
+activated, the command will affect that same subtree.
+@end table
+@c @end quotation
-@item
-If none of the select tags is found, the whole buffer will be selected for
-export.
+Normally the entire buffer is exported, but if there is an active region
+only that part of the buffer will be exported.
-@item
-Finally, all subtrees that are marked by any of the @emph{exclude} tags will
-be removed from the export buffer.
-@end enumerate
+Export options can also, among other things, affect the scope of export
+process. They are toggled from the dispatcher with appropriate key
+combinations:
-The variable @var{org-export-with-tasks} can be configured to select which
-kind of tasks should be included for export. See the docstring of the
-variable for more information.
+@table @kbd
+@item C-a
+@vindex org-export-async-init-file
+@vindex org-export-run-in-background
+Toggles asynchronous export. The export happens in an external Emacs
+process@footnote{Configure @var{org-export-async-init-file} to properly set
+it up.}.
-@node Export options, The export dispatcher, Selective export, Exporting
-@section Export options
-@cindex options, for export
+In this case, no output is displayed automatically. It is stored in a list
+called the export stack, and can be viewed from there. The stack can be
+reached by calling the dispatcher with a double @kbd{C-u} prefix argument,
+or with @kbd{&} key from the dispatcher.
-@cindex completion, of option keywords
-The exporter recognizes special lines in the buffer which provide
-additional information. These lines may be put anywhere in the file.
-The whole set of lines can be inserted into the buffer with @kbd{C-c
-C-e t}. For individual lines, a good way to make sure the keyword is
-correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
-(@pxref{Completion}). For a summary of other in-buffer settings not
-specifically related to export, see @ref{In-buffer settings}.
+To make this behaviour the default, customize the variable successfully
+@var{org-export-run-in-background}.
-In particular, note that you can place commonly-used (export) options in
-a separate file which can be included using @code{#+SETUPFILE}.
+@item C-b
+Toggles body-only export. Its effect, if any, depends on the back-end
+used. Its purpose is to remove all meta-data from output and focus on the
+real contents.
-@cindex #+TITLE
-@cindex #+AUTHOR
-@cindex #+DATE
-@cindex #+EMAIL
-@cindex #+DESCRIPTION
-@cindex #+KEYWORDS
-@cindex #+LANGUAGE
-@cindex #+TEXT
-@cindex #+OPTIONS
-@cindex #+BIND
-@cindex #HTML_HEAD
-@cindex #+HTML_LINK_UP
-@cindex #+HTML_LINK_HOME
-@cindex #+SELECT_TAGS
-@cindex #+EXCLUDE_TAGS
-@cindex #+LATEX_HEADER
-@cindex #+LATEX_HEADER_EXTRA
+@item C-s
+@vindex org-export-initial-scope
+Toggles subtree export. The top heading becomes the document title and is
+removed from the contents.
+
+You can change the default state of this option by setting
+@var{org-export-initial-scope}.
+
+@item C-v
+Toggles visible-only export. Only export the text that is currently
+visible, i.e. not hidden by outline visibility in the buffer.
+
+@end table
+
+@vindex org-export-copy-to-kill-ring
+Unless it happened asynchronously, a successful export process usually
+stores its output into the kill-ring. You can configure
+@var{org-export-copy-to-kill-ring} in order to change this behaviour.
+
+@node Export formats, Export settings, The Export Dispatcher, Exporting
+@section Export formats
+@cindex Export, formats
+
+Libraries translating an Org buffer into a foreign format are called export
+back-ends. An export format is not available until the proper back-end has
+been loaded.
+
+@vindex org-export-backends
+By default, the following four back-ends are ready to use: @code{ascii},
+@code{html}, @code{icalendar} and @code{latex}. It is possible to add more
+(or remove some) by customizing @var{org-export-backends}.
+
+Core back-ends include:
+
+@itemize
+@item ascii (ASCII format)
+@item beamer (@LaTeX{} Beamer format)
+@item html (HTML format)
+@item icalendar (iCalendar format)
+@item latex (@LaTeX{} format)
+@item man (Man page format)
+@item md (Markdown format)
+@item odt (OpenDocument Text format)
+@item texinfo (Texinfo format)
+@end itemize
+
+More are available from the @code{contrib/} directory available from the
+distribution archives or from GNU/Org ELPA.
+
+@node Export settings, ASCII/Latin-1/UTF-8 export, Export formats, Exporting
+@section Export settings
+@cindex Export, settings
+
+Export output can be controlled through a number of export options. These
+can be set globally with variables, and overridden on a per-buffer basis
+with keywords. Such keywords may be put anywhere in the file. For
+individual lines, a good way to make sure the keyword is correct is to type
+@code{#+} and then use @kbd{M-<TAB>} completion.
+
+Here is an exhaustive list of such keywords along with the equivalent
+global variable. Only options available for every back-end are discussed
+in this section.
+
+@table @samp
+@item AUTHOR
@vindex user-full-name
+the author (@var{user-full-name}).
+
+@item CREATOR
+@vindex org-export-creator-string
+entity responsible for output generation (@var{org-export-creator-string}).
+
+@item DATE
+@vindex org-export-date-timestamp-format
+A date or a time-stamp@footnote{The variable
+@var{org-export-date-timestamp-format} defines how this time-stamp will be
+exported.}.
+
+@item DESCRIPTION
+the page description, e.g., for the XHTML meta tag.
+
+@item EMAIL
@vindex user-mail-address
+email address (@var{user-mail-address}.)
+
+@item EXCLUDE_TAGS
+Tags that exclude a tree from export
+
+@item KEYWORDS
+keywords defining the contents, e.g., for the XHTML meta tag.
+
+@item LANGUAGE
@vindex org-export-default-language
-@vindex org-export-allow-bind-keywords
-@example
-#+TITLE: the title to be shown (default is the buffer name)
-#+AUTHOR: the author (default taken from @code{user-full-name})
-#+DATE: a date, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, or a format string for @code{format-time-string}
-#+EMAIL: his/her email address (default from @code{user-mail-address})
-#+DESCRIPTION: the page description, e.g., for the XHTML meta tag
-#+KEYWORDS: the page keywords, e.g., for the XHTML meta tag
-#+LANGUAGE: language for HTML, e.g., @samp{en} (@code{org-export-default-language})
-#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
-#+BIND: lisp-var lisp-val, e.g., @code{org-latex-image-default-width ".7\\linewidth"}
- @r{Configure @code{org-export-allow-bind-keywords} to use this}
-#+HTML_HEAD: Additional line to the @samp{<head>...</head>} of the HTML output
-#+HTML_LINK_UP: the ``up'' link of an exported page
-#+HTML_LINK_HOME: the ``home'' link of an exported page
-#+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@}
-#+LATEX_HEADER_EXTRA: similar to #+LATEX_HEADER, but ignored when previewing math snippets
-#+SELECT_TAGS: Tags that select a tree for export
-#+EXCLUDE_TAGS: Tags that exclude a tree from export
-@end example
+language used for translation of some strings
+(@var{org-export-default-language}).
-@noindent
-The @code{#+OPTIONS} line is a compact@footnote{If you want to configure many options
-this way, you can use several @code{#+OPTIONS} lines.} form to specify export
-settings. Here you can:
-@cindex headline levels
-@cindex section-numbers
-@cindex table of contents
-@cindex line-break preservation
-@cindex quoted HTML tags
-@cindex fixed-width sections
-@cindex tables
-@cindex @TeX{}-like syntax for sub- and superscripts
-@cindex footnotes
-@cindex special strings
-@cindex emphasized text
-@cindex @TeX{} macros
-@cindex @LaTeX{} fragments
-@cindex author info, in export
-@cindex time info, in export
-@vindex org-export-author-info
-@vindex org-export-creator-info
-@vindex org-export-email-info
+@item SELECT_TAGS
+@vindex org-export-select-tags
+Tags that select a tree for export (@var{org-export-select-tags}).
+
+@item TITLE
+the title to be shown (otherwise derived from buffer's name).
+@end table
+
+Additionally, the @code{OPTIONS} keyword is a compact@footnote{If you want
+to configure many options this way, you can use several @code{#+OPTIONS}
+lines.} form to specify export settings. Here you can:
+
+@table @code
+@item ':
+@vindex org-export-with-smart-quotes
+toggle smart quotes (@var{org-export-with-smart-quotes}).
+
+@item *:
+toggle emphasized text (@var{org-export-with-emphasize}).
+
+@item -:
+@vindex org-export-with-special-strings
+toggle conversion of special strings
+(@var{org-export-with-special-strings}).
+
+@item ::
+@vindex org-export-with-fixed-width
+toggle fixed-width sections
+(@var{org-export-with-fixed-width}).
+
+@item <:
+@vindex org-export-with-timestamps
+toggle inclusion of any time/date stamps like DEADLINES
+(@var{org-export-with-timestamps}).
+
+@item :
+@vindex org-export-preserve-breaks
+toggle line-break-preservation (@var{org-export-preserve-breaks}).
+
+@item ^: FIXME
+@vindex org-export-with-sub-superscripts
+toggle @TeX{}-like syntax for sub- and superscripts. If you write
+"^:@{@}", 'a@math{_b}' will be interpreted, but the simple 'a_b' will be
+left as it is (@var{org-export-with-sub-superscripts}).
+
+@item arch:
+@vindex org-export-with-archived-trees
+configure export of archived trees. Can be set to @code{headline} to only
+process the headline, skipping its contents
+(@var{org-export-with-archived-trees}).
+
+@item author:
+@vindex org-export-with-author
+toggle inclusion of author name into exported file
+(@var{org-export-with-author}).
+
+@item c:
+@vindex org-export-with-clocks
+toggle inclusion of CLOCK keywords (@var{org-export-with-clocks}).
+
+@item creator:
+@vindex org-export-with-creator
+configure inclusion of creator info into exported file. It may be set to
+@code{comment} (@var{org-export-with-creator}).
+
+@item d:
+@vindex org-export-with-drawers
+toggle inclusion of drawers, or list drawers to include
+(@var{org-export-with-drawers}).
+
+@item e:
+@vindex org-export-with-entities
+toggle inclusion of entities (@var{org-export-with-entities}).
+
+@item email:
+@vindex org-export-with-email
+toggle inclusion of author email into exported file
+(@var{org-export-with-email}).
+
+@item f:
+@vindex org-export-with-footnotes
+toggle footnotes (@var{org-export-with-footnotes}).
+
+@item H:
+@vindex org-export-headline-levels
+set the number of headline levels for export
+(@var{org-export-headline-levels}).
+
+@item inline:
+@vindex org-export-with-inlinetasks
+toggle inclusion of inlinetasks (@var{org-export-with-inlinetasks}).
+
+@item num:
+@vindex org-export-with-section-numbers
+toggle section-numbers (@var{org-export-with-section-numbers})
+
+@item pri:
+@vindex org-export-with-priority
+toggle priority cookies (@var{org-export-with-priority}).
+
+@item stat:
+@vindex org-export-with-statistics-cookies
+toggle inclusion of statistics cookies
+(@var{org-export-with-statistics-cookies}).
+
+@item tags:
+@vindex org-export-with-tags
+toggle inclusion of tags, may also be @code{not-in-toc}
+(@var{org-export-with-tags}).
+
+@item tasks:
+@vindex org-export-with-tasks
+toggle inclusion of tasks (TODO items), can be @code{nil} to remove all
+tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep
+(@var{org-export-with-tasks}).
+
+@item tex:
+@vindex org-export-with-latex
+configure export of @LaTeX{} fragments and environments. It may be set to
+@code{verbatim} (@var{org-export-with-latex}).
+
+@item timestamp:
@vindex org-export-time-stamp-file
-@example
-H: @r{set the number of headline levels for export}
-num: @r{turn on/off section-numbers}
-toc: @r{turn on/off table of contents, or set level limit (integer)}
-\n: @r{turn on/off line-break-preservation (DOES NOT WORK)}
-@@: @r{turn on/off quoted HTML tags}
-:: @r{turn on/off fixed-width sections}
-|: @r{turn on/off tables}
-^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If}
- @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but}
- @r{the simple @code{a_b} will be left as it is.}
--: @r{turn on/off conversion of special strings.}
-f: @r{turn on/off footnotes like this[1].}
-todo: @r{turn on/off inclusion of TODO keywords into exported text}
-tasks: @r{turn on/off inclusion of tasks (TODO items), can be nil to remove}
- @r{all tasks, @code{todo} to remove DONE tasks, or list of kwds to keep}
-pri: @r{turn on/off priority cookies}
-tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}}
-<: @r{turn on/off inclusion of any time/date stamps like DEADLINES}
-*: @r{turn on/off emphasized text (bold, italic, underlined)}
-TeX: @r{turn on/off simple @TeX{} macros in plain text}
-LaTeX: @r{configure export of @LaTeX{} fragments. Default @code{auto}}
-skip: @r{turn on/off skipping the text before the first heading}
-author: @r{turn on/off inclusion of author name/email into exported file}
-email: @r{turn on/off inclusion of author email into exported file}
-creator: @r{turn on/off inclusion of creator info into exported file}
-timestamp: @r{turn on/off inclusion creation time into exported file}
-d: @r{turn on/off inclusion of drawers, or list drawers to include}
-@end example
-@noindent
-These options take effect in both the HTML and @LaTeX{} export, except for
-@code{TeX} and @code{LaTeX} options, which are respectively @code{t} and
-@code{nil} for the @LaTeX{} export.
-
-When exporting only a single subtree by selecting it with @kbd{C-c @@} before
-calling an export command, the subtree can overrule some of the file's export
-settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE},
-@code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and
-@code{EXPORT_OPTIONS}.
-
-@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting
-@section The export dispatcher
-@cindex dispatcher, for export commands
-
-All export commands can be reached using the export dispatcher, which is a
-prefix key that prompts for an additional key specifying the command.
-Normally the entire file is exported, but if there is an active region that
-contains one outline tree, the first heading is used as document title and
-the subtrees are exported.
+toggle inclusion creation time into exported file
+(@var{org-export-time-stamp-file}).
+
+@item toc:
+@vindex org-export-with-toc
+toggle table of contents, or set level limit (@var{org-export-with-toc}).
+
+@item todo:
+@vindex org-export-with-todo-keywords
+toggle inclusion of TODO keywords into exported text
+(@var{org-export-with-todo-keywords}).
+
+@item |:
+@vindex org-export-with-tables
+toggle tables (@var{org-export-with-tables}).
-@table @kbd
-@orgcmd{C-c C-e,org-export}
-Dispatcher for export and publishing commands. Displays a help-window
-listing the additional key(s) needed to launch an export or publishing
-command. The prefix arg is passed through to the exporter. A double prefix
-@kbd{C-u C-u} causes most commands to be executed in the background, in a
-separate Emacs process@footnote{To make this behavior the default, customize
-the variable @code{org-export-run-in-background}.}.
-@orgcmd{C-c C-e C-v,org-export-visible}
-Like @kbd{C-c C-e}, but only export the text that is currently visible
-(i.e., not hidden by outline visibility).
-@orgcmd{C-u C-u C-c C-e,org-export}
-@vindex org-export-run-in-background
-Call the exporter, but reverse the setting of
-@code{org-export-run-in-background}, i.e., request background processing if
-not set, or force processing in the current Emacs process if set.
@end table
-@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting
+A more general mechanism is also provided. Indeed, Emacs variables can
+become buffer-local during export by using the BIND keyword. Its syntax is
+@samp{#+BIND: variable value}. This is particularly useful for in-buffer
+settings that cannot be changed using specific keywords.
+
+You can place commonly-used export settings in a separate file which can be
+included using @samp{#+SETUPFILE: "filename"} syntax.
+
+These settings affect all buffer's export processes. Though, it is
+possible to override them locally when exporting only a subtree. This is
+done by adding a headline property named after the keyword with the
+@samp{EXPORT_} prefix. For example, @samp{DATE} and @samp{OPTIONS}
+keywords become, respectively @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}
+properties. Subtree export also supports the self-explicit
+@samp{EXPORT_FILE_NAME} property@footnote{There is no buffer-wide
+equivalent for this property. The file name in this case is derived from
+the file associated to the buffer, if possible, or asked to the user
+otherwise.}.
+
+@node ASCII/Latin-1/UTF-8 export, HTML export, Export settings, Exporting
@section ASCII/Latin-1/UTF-8 export
@cindex ASCII export
@cindex Latin-1 export
@@ -12366,13 +12491,11 @@ both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and
@LaTeX{} export. See @code{org-export-plist-vars} to check this list of
options.
-
-
@vindex org-publish-project-alist
-When a property is given a value in @code{org-publish-project-alist},
-its setting overrides the value of the corresponding user variable (if
-any) during publishing. Options set within a file (@pxref{Export
-options}), however, override everything.
+When a property is given a value in @code{org-publish-project-alist}, its
+setting overrides the value of the corresponding user variable (if any)
+during publishing. Options set within a file (@pxref{Export settings}),
+however, override everything.
@node Publishing links, Sitemap, Publishing options, Configuration
@subsection Links between published files
@@ -15002,7 +15125,7 @@ multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
@itemx #+HTML_HEAD:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
@itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
These lines provide settings for exporting files. For more details see
-@ref{Export options}.
+@ref{Export settings}.
@item #+TODO: #+SEQ_TODO: #+TYP_TODO:
@vindex org-todo-keywords
These lines set the TODO keywords and their interpretation in the