ndwarshuis
/
org-mode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

org.texi: More rewriting 

* org.texi (Export back-ends): Rename from "Export formats".
(The Export Dispatcher, Export settings): Minor rewrites.
(ASCII/Latin-1/UTF-8 export): Update variable's name.
(In-buffer settings): Add #+HTML_HEAD_EXTRA.

Thanks to Thomas Dye for these suggestions.
This commit is contained in:
Bastien Guerry 2013-04-15 22:01:03 +02:00
parent 5ec66d165c
commit bd00b097b0
1 changed files with 118 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
doc/org.texi
View File

@ -580,7 +580,7 @@ Embedded @LaTeX{}
Exporting Exporting
* The Export Dispatcher:: The main exporter interface * The Export Dispatcher:: The main exporter interface
* Export formats:: Available export formats * Export back-ends:: Built-in export formats
* Export settings:: Generic export settings * Export settings:: Generic export settings
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* Beamer export:: Exporting as a Beamer presentation * Beamer export:: Exporting as a Beamer presentation
@ -9894,8 +9894,8 @@ given, the text will be assumed to be in Org mode format and will be
processed normally. processed normally.
Contents of the included file will belong to the same structure (headline, Contents of the included file will belong to the same structure (headline,
item) containing the INCLUDE keyword. In particular, headlines within the item) containing the @code{INCLUDE} keyword. In particular, headlines within
file will become children of the current section. That behaviour can be the file will become children of the current section. That behaviour can be
changed by providing an additional keyword parameter, @code{:minlevel}. In 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 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 the lowest level reaches that specified level. For example, to make a file
@ -10287,7 +10287,7 @@ in the iCalendar format.
@menu @menu
* The Export Dispatcher:: The main exporter interface * The Export Dispatcher:: The main exporter interface
* Export formats:: Available export formats * Export back-ends:: Built-in export formats
* Export settings:: Generic export settings * Export settings:: Generic export settings
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* Beamer export:: Exporting as a Beamer presentation * Beamer export:: Exporting as a Beamer presentation
@ -10300,91 +10300,90 @@ in the iCalendar format.
* Advanced configuration:: Fine-tuning the export output * Advanced configuration:: Fine-tuning the export output
@end menu @end menu
@node The Export Dispatcher, Export formats, Exporting, Exporting @node The Export Dispatcher, Export back-ends, Exporting, Exporting
@section The Export Dispatcher @section The Export Dispatcher
@vindex org-export-dispatch-use-expert-ui @vindex org-export-dispatch-use-expert-ui
@cindex Export, dispatcher @cindex Export, dispatcher
The main entry point for any export related task is the dispatcher, a The main entry point for export related tasks is the dispatcher, a
hierarchical menu@footnote{It is also possible to use a less intrusive hierarchical menu from which it is possible to select an export format and
interface by setting @var{org-export-dispatch-use-expert-ui} to a non-@code{nil} toggle export options@footnote{It is also possible to use a less intrusive
value. In that case, only a prompt is visible from the minibuffer. From interface by setting @var{org-export-dispatch-use-expert-ui} to a
there one can still switch back to regular menu with @kbd{?} key.} from non-@code{nil} value. In that case, only a prompt is visible from the
which it is possible to select an export format and to toggle export minibuffer. From there one can still switch back to regular menu by pressing
options. @key{?}.} from which it is possible to select an export format and to toggle
export options.
@c @quotation @c @quotation
@table @asis @table @asis
@orgcmd{C-c C-e,org-export-dispatch} @orgcmd{C-c C-e,org-export-dispatch}
Dispatch for export and publishing commands. When called with @kbd{C-u} Dispatch for export and publishing commands. When called with a @kbd{C-u}
prefix argument, repeat last command, preserving toggled options, on prefix argument, repeat the last export command on the current buffer while
current buffer. If the active buffer hasn't changed and subtree export was preserving toggled options. If the current buffer hasn't changed and subtree
activated, the command will affect that same subtree. export was activated, the command will affect that same subtree.
@end table @end table
@c @end quotation @c @end quotation
Normally the entire buffer is exported, but if there is an active region Normally the entire buffer is exported, but if there is an active region
only that part of the buffer will be exported. only that part of the buffer will be exported.
Export options can also, among other things, affect the scope of export Several export options (@pxref{Export settings}) can be toggled from the
process. They are toggled from the dispatcher with appropriate key export dispatcher with the following key combinations:
combinations:
@table @kbd @table @kbd
@item C-a @item C-a
@vindex org-export-async-init-file @vindex org-export-async-init-file
Toggles asynchronous export. The export happens in an external Emacs Toggle asynchronous export. Asynchronous export uses an external Emacs
process@footnote{Configure @var{org-export-async-init-file} to properly set process that is configured with a specified initialization file
it up.}. (@pxref{Configuring asynchronous export}).
In this case, no output is displayed automatically. It is stored in a list While exporting asynchronously, the output is not displayed. It is stored in
called the export stack, and can be viewed from there. The stack can be a list called ``the export stack'', and can be viewed from there. The stack
reached by calling the dispatcher with a double @kbd{C-u} prefix argument, can be reached by calling the dispatcher with a double @kbd{C-u} prefix
or with @kbd{&} key from the dispatcher. argument, or with @kbd{&} key from the dispatcher.
@vindex org-export-in-background @vindex org-export-in-background
To make this behaviour the default, customize the variable To make this behaviour the default, customize the variable
@var{org-export-in-background}. @var{org-export-in-background}.
@item C-b @item C-b
Toggles body-only export. Its effect, if any, depends on the back-end Toggle body-only export. Its effect depends on the back-end used.
used. Its purpose is to remove all meta-data from output and focus on the Typically, if the back-end has a header section (like @code{<head>...</head>}
real contents. in the HTML back-end), a body-only export will not include this header.
@item C-s @item C-s
@vindex org-export-initial-scope @vindex org-export-initial-scope
Toggles subtree export. The top heading becomes the document title and is Toggle subtree export. The top heading becomes the document title.
removed from the contents.
You can change the default state of this option by setting You can change the default state of this option by setting
@var{org-export-initial-scope}. @var{org-export-initial-scope}.
@item C-v @item C-v
Toggles visible-only export. Only export the text that is currently Toggle visible-only export. Only export the text that is currently
visible, i.e. not hidden by outline visibility in the buffer. visible, i.e. not hidden by outline visibility in the buffer.
@end table @end table
@vindex org-export-copy-to-kill-ring @vindex org-export-copy-to-kill-ring
Unless it happened asynchronously, a successful export process usually With the exception of asynchronous export, a successful export process writes
stores its output into the kill-ring. You can configure its output to the kill-ring. You can configure this behavior by altering the
@var{org-export-copy-to-kill-ring} in order to change this behaviour. option @var{org-export-copy-to-kill-ring}.
@node Export formats, Export settings, The Export Dispatcher, Exporting @node Export back-ends, Export settings, The Export Dispatcher, Exporting
@section Export formats @section Export back-ends
@cindex Export, formats @cindex Export, back-ends
Libraries translating an Org buffer into a foreign format are called export An export back-end is a library that translates Org syntax into a foreign
back-ends. An export format is not available until the proper back-end has format. An export format is not available until the proper back-end has been
been loaded. loaded.
@vindex org-export-backends @vindex org-export-backends
By default, the following four back-ends are ready to use: @code{ascii}, By default, the following four back-ends are loaded: @code{ascii},
@code{html}, @code{icalendar} and @code{latex}. It is possible to add more @code{html}, @code{icalendar} and @code{latex}. It is possible to add more
(or remove some) by customizing @var{org-export-backends}. (or remove some) by customizing @var{org-export-backends}.
Core back-ends include: Built-in back-ends include:
@itemize @itemize
@item ascii (ASCII format) @item ascii (ASCII format)
@ -10398,31 +10397,39 @@ Core back-ends include:
@item texinfo (Texinfo format) @item texinfo (Texinfo format)
@end itemize @end itemize
More are available from the @code{contrib/} directory available from the Other back-ends might be found in the @code{contrib/} directory
distribution archives or from GNU/Org ELPA. (@pxref{Installation}).
@node Export settings, ASCII/Latin-1/UTF-8 export, Export formats, Exporting @node Export settings, ASCII/Latin-1/UTF-8 export, Export back-ends, Exporting
@section Export settings @section Export settings
@cindex Export, settings @cindex Export, settings
Export output can be controlled through a number of export options. These Export options can be set: globally with variables; for an individual file by
can be set globally with variables, and overridden on a per-buffer basis with making variables buffer-local with in-buffer settings (@pxref{In-buffer
keywords. Such keywords may be put anywhere in the file. For individual settings}), by setting individual keywords, or by specifying them in a
lines, a good way to make sure the keyword is correct is to type @code{#+} compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
and then use @kbd{M-<TAB>} completion. properties (@pxref{Properties and Columns}). Options set at a specific level
override options set at a more general level.
Here is an exhaustive list of such keywords along with the equivalent global In-buffer settings may appear anywhere in the file, either directly or
variable. Only options available for every back-end are discussed in this indirectly through a file included using @code{#+SETUPFILE}. Option keyword
section. sets tailored to a particular back-end can be inserted from the export
dispatcher (@pxref{The export dispatcher}) using the @code{Insert template}
command by pressing @key{#}. To insert keywords individually, a good way to
make sure the keyword is correct is to type @code{#+} and then to use
@kbd{M-<TAB>} for completion.
The export keywords available for every back-end, and their equivalent global
variables, include:
@table @samp @table @samp
@item AUTHOR @item AUTHOR
@vindex user-full-name @vindex user-full-name
the author (@var{user-full-name}). The author (@var{user-full-name}).
@item CREATOR @item CREATOR
@vindex org-export-creator-string @vindex org-export-creator-string
entity responsible for output generation (@var{org-export-creator-string}). Entity responsible for output generation (@var{org-export-creator-string}).
@item DATE @item DATE
@vindex org-export-date-timestamp-format @vindex org-export-date-timestamp-format
@ -10431,174 +10438,176 @@ A date or a time-stamp@footnote{The variable
exported.}. exported.}.
@item DESCRIPTION @item DESCRIPTION
the page description, e.g., for the XHTML meta tag. The page description, e.g., for the XHTML meta tag.
@item EMAIL @item EMAIL
@vindex user-mail-address @vindex user-mail-address
email address (@var{user-mail-address}). The email address (@var{user-mail-address}).
@item KEYWORDS @item KEYWORDS
keywords defining the contents, e.g., for the XHTML meta tag. The keywords defining the contents, e.g., for the XHTML meta tag.
@item LANGUAGE @item LANGUAGE
@vindex org-export-default-language @vindex org-export-default-language
language used for translation of some strings The language used for translating some strings
(@var{org-export-default-language}). (@var{org-export-default-language}). E.g., @samp{#+LANGUAGE: fr} will tell
Org to translate @emph{File} (english) into @emph{Fichier} (french) in the
clocktable.
@item SELECT_TAGS @item SELECT_TAGS
@vindex org-export-select-tags @vindex org-export-select-tags
Tags that select a tree for export (@var{org-export-select-tags}). The The tags that select a tree for export (@var{org-export-select-tags}). The
default value is @code{:export:}. Within a subtree tagged with default value is @code{:export:}. Within a subtree tagged with
@code{:export:}, you can still exclude entries with @code{:noexport:} (see @code{:export:}, you can still exclude entries with @code{:noexport:} (see
below). below).
@item EXCLUDE_TAGS @item EXCLUDE_TAGS
Tags that exclude a tree from export (@var{org-export-exclude-tags}). The The tags that exclude a tree from export (@var{org-export-exclude-tags}).
default value is @code{:noexport:}. Entries with the @code{:noexport:} tag The default value is @code{:noexport:}. Entries with the @code{:noexport:}
will be unconditionally excluded from the export, even if they have an tag will be unconditionally excluded from the export, even if they have an
@code{:export:} tag. @code{:export:} tag.
@item TITLE @item TITLE
the title to be shown (otherwise derived from buffer's name). The title to be shown (otherwise derived from buffer's name).
@end table @end table
Additionally, the @code{OPTIONS} keyword is a compact@footnote{If you want The @code{#+OPTIONS} keyword is a compact@footnote{If you want to configure
to configure many options this way, you can use several @code{#+OPTIONS} many options this way, you can use several @code{#+OPTIONS} lines.} form that
lines.} form to specify export settings. Here you can: recognizes the following arguments:
@table @code @table @code
@item ': @item ':
@vindex org-export-with-smart-quotes @vindex org-export-with-smart-quotes
toggle smart quotes (@var{org-export-with-smart-quotes}). Toggle smart quotes (@var{org-export-with-smart-quotes}).
@item *: @item *:
toggle emphasized text (@var{org-export-with-emphasize}). Toggle emphasized text (@var{org-export-with-emphasize}).
@item -: @item -:
@vindex org-export-with-special-strings @vindex org-export-with-special-strings
toggle conversion of special strings Toggle conversion of special strings
(@var{org-export-with-special-strings}). (@var{org-export-with-special-strings}).
@item :: @item ::
@vindex org-export-with-fixed-width @vindex org-export-with-fixed-width
toggle fixed-width sections Toggle fixed-width sections
(@var{org-export-with-fixed-width}). (@var{org-export-with-fixed-width}).
@item <: @item <:
@vindex org-export-with-timestamps @vindex org-export-with-timestamps
toggle inclusion of any time/date active/inactive stamps Toggle inclusion of any time/date active/inactive stamps
(@var{org-export-with-timestamps}). (@var{org-export-with-timestamps}).
@item : @item :
@vindex org-export-preserve-breaks @vindex org-export-preserve-breaks
toggle line-break-preservation (@var{org-export-preserve-breaks}). Toggle line-break-preservation (@var{org-export-preserve-breaks}).
@item ^: @item ^:
@vindex org-export-with-sub-superscripts @vindex org-export-with-sub-superscripts
toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}", Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
@samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as @samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
it is (@var{org-export-with-sub-superscripts}). it is (@var{org-export-with-sub-superscripts}).
@item arch: @item arch:
@vindex org-export-with-archived-trees @vindex org-export-with-archived-trees
configure export of archived trees. Can be set to @code{headline} to only Configure export of archived trees. Can be set to @code{headline} to only
process the headline, skipping its contents process the headline, skipping its contents
(@var{org-export-with-archived-trees}). (@var{org-export-with-archived-trees}).
@item author: @item author:
@vindex org-export-with-author @vindex org-export-with-author
toggle inclusion of author name into exported file Toggle inclusion of author name into exported file
(@var{org-export-with-author}). (@var{org-export-with-author}).
@item c: @item c:
@vindex org-export-with-clocks @vindex org-export-with-clocks
toggle inclusion of CLOCK keywords (@var{org-export-with-clocks}). Toggle inclusion of CLOCK keywords (@var{org-export-with-clocks}).
@item creator: @item creator:
@vindex org-export-with-creator @vindex org-export-with-creator
configure inclusion of creator info into exported file. It may be set to Configure inclusion of creator info into exported file. It may be set to
@code{comment} (@var{org-export-with-creator}). @code{comment} (@var{org-export-with-creator}).
@item d: @item d:
@vindex org-export-with-drawers @vindex org-export-with-drawers
toggle inclusion of drawers, or list drawers to include Toggle inclusion of drawers, or list drawers to include
(@var{org-export-with-drawers}). (@var{org-export-with-drawers}).
@item e: @item e:
@vindex org-export-with-entities @vindex org-export-with-entities
toggle inclusion of entities (@var{org-export-with-entities}). Toggle inclusion of entities (@var{org-export-with-entities}).
@item email: @item email:
@vindex org-export-with-email @vindex org-export-with-email
toggle inclusion of author email into exported file Toggle inclusion of the author's e-mail into exported file
(@var{org-export-with-email}). (@var{org-export-with-email}).
@item f: @item f:
@vindex org-export-with-footnotes @vindex org-export-with-footnotes
toggle footnotes (@var{org-export-with-footnotes}). Toggle the inclusion of footnotes (@var{org-export-with-footnotes}).
@item H: @item H:
@vindex org-export-headline-levels @vindex org-export-headline-levels
set the number of headline levels for export Set the number of headline levels for export
(@var{org-export-headline-levels}). (@var{org-export-headline-levels}).
@item inline: @item inline:
@vindex org-export-with-inlinetasks @vindex org-export-with-inlinetasks
toggle inclusion of inlinetasks (@var{org-export-with-inlinetasks}). Toggle inclusion of inlinetasks (@var{org-export-with-inlinetasks}).
@item num: @item num:
@vindex org-export-with-section-numbers @vindex org-export-with-section-numbers
toggle section-numbers (@var{org-export-with-section-numbers}). Toggle section-numbers (@var{org-export-with-section-numbers}).
@item p: @item p:
@vindex org-export-with-planning @vindex org-export-with-planning
toggle export of planning information (@var{org-export-with-planning}). Toggle export of planning information (@var{org-export-with-planning}).
``Planning information'' is the line containing the @code{SCHEDULED:}, the ``Planning information'' is the line containing the @code{SCHEDULED:}, the
@code{DEADLINE:} or the @code{CLOSED:} cookies or a combination of them. @code{DEADLINE:} or the @code{CLOSED:} cookies or a combination of them.
@item pri: @item pri:
@vindex org-export-with-priority @vindex org-export-with-priority
toggle priority cookies (@var{org-export-with-priority}). Toggle priority cookies (@var{org-export-with-priority}).
@item stat: @item stat:
@vindex org-export-with-statistics-cookies @vindex org-export-with-statistics-cookies
toggle inclusion of statistics cookies Toggle inclusion of statistics cookies
(@var{org-export-with-statistics-cookies}). (@var{org-export-with-statistics-cookies}).
@item tags: @item tags:
@vindex org-export-with-tags @vindex org-export-with-tags
toggle inclusion of tags, may also be @code{not-in-toc} Toggle inclusion of tags, may also be @code{not-in-toc}
(@var{org-export-with-tags}). (@var{org-export-with-tags}).
@item tasks: @item tasks:
@vindex org-export-with-tasks @vindex org-export-with-tasks
toggle inclusion of tasks (TODO items), can be @code{nil} to remove all 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 tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep
(@var{org-export-with-tasks}). (@var{org-export-with-tasks}).
@item tex: @item tex:
@vindex org-export-with-latex @vindex org-export-with-latex
configure export of @LaTeX{} fragments and environments. It may be set to Configure export of @LaTeX{} fragments and environments. It may be set to
@code{verbatim} (@var{org-export-with-latex}). @code{verbatim} (@var{org-export-with-latex}).
@item timestamp: @item timestamp:
@vindex org-export-time-stamp-file @vindex org-export-time-stamp-file
toggle inclusion creation time into exported file Toggle inclusion of the creation time into exported file
(@var{org-export-time-stamp-file}). (@var{org-export-time-stamp-file}).
@item toc: @item toc:
@vindex org-export-with-toc @vindex org-export-with-toc
toggle table of contents, or set level limit (@var{org-export-with-toc}). Toggle inclusion of the table of contents, or set the level limit
(@var{org-export-with-toc}).
@item todo: @item todo:
@vindex org-export-with-todo-keywords @vindex org-export-with-todo-keywords
toggle inclusion of TODO keywords into exported text Toggle inclusion of TODO keywords into exported text
(@var{org-export-with-todo-keywords}). (@var{org-export-with-todo-keywords}).
@item |: @item |:
@vindex org-export-with-tables @vindex org-export-with-tables
toggle tables (@var{org-export-with-tables}). Toggle inclusion of tables (@var{org-export-with-tables}).
@end table @end table
A more general mechanism is also provided. Indeed, Emacs variables can A more general mechanism is also provided. Indeed, Emacs variables can
@ -10609,16 +10618,15 @@ settings that cannot be changed using specific keywords.
You can place commonly-used export settings in a separate file which can be You can place commonly-used export settings in a separate file which can be
included using @samp{#+SETUPFILE: filename} syntax. included using @samp{#+SETUPFILE: filename} syntax.
These settings affect all buffer's export processes. Though, it is These settings affect all buffer's export processes. Though, it is possible
possible to override them locally when exporting only a subtree. This is to override them locally when exporting only a subtree. This is done by
done by adding a headline property named after the keyword with the adding a headline property named after the keyword with the @samp{EXPORT_}
@samp{EXPORT_} prefix. For example, @samp{DATE} and @samp{OPTIONS} prefix. For example, @samp{DATE} and @samp{OPTIONS} keywords become,
keywords become, respectively @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS} respectively @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS} properties.
properties. Subtree export also supports the self-explicit Subtree export also supports the self-explicit @samp{EXPORT_FILE_NAME}
@samp{EXPORT_FILE_NAME} property@footnote{There is no buffer-wide property@footnote{There is no buffer-wide equivalent for this property. The
equivalent for this property. The file name in this case is derived from file name in this case is derived from the file associated to the buffer, if
the file associated to the buffer, if possible, or asked to the user possible, or asked to the user otherwise.}.
otherwise.}.
@node ASCII/Latin-1/UTF-8 export, Beamer export, Export settings, Exporting @node ASCII/Latin-1/UTF-8 export, Beamer export, Export settings, Exporting
@section ASCII/Latin-1/UTF-8 export @section ASCII/Latin-1/UTF-8 export
@ -10968,7 +10976,7 @@ Export only the visible part of the document.
@vindex org-html-validation-link @vindex org-html-validation-link
@vindex org-export-author-info @vindex org-export-author-info
@vindex org-export-email-info @vindex org-export-email-info
@vindex org-export-creator-info @vindex org-export-creator-string
@vindex org-export-time-stamp-file @vindex org-export-time-stamp-file
The HTML exporter lets you define a preamble and a postamble. The HTML exporter lets you define a preamble and a postamble.
@ -15698,7 +15706,7 @@ multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
@itemx #+OPTIONS:, #+BIND:, @itemx #+OPTIONS:, #+BIND:,
@itemx #+DESCRIPTION:, #+KEYWORDS:, @itemx #+DESCRIPTION:, #+KEYWORDS:,
@itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:, @itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:,
@itemx #+HTML_HEAD:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:, @itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
@itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS: @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
These lines provide settings for exporting files. For more details see These lines provide settings for exporting files. For more details see
@ref{Export settings}. @ref{Export settings}.