diff options
Diffstat (limited to 'doc/misc/org.texi')
| -rw-r--r-- | doc/misc/org.texi | 2313 |
1 files changed, 1607 insertions, 706 deletions
diff --git a/doc/misc/org.texi b/doc/misc/org.texi index a6fae5e216f..bc82e0ba7fe 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -4,8 +4,8 @@ @setfilename ../../info/org @settitle The Org Manual -@set VERSION 7.7 -@set DATE July 2011 +@set VERSION 7.8.03 +@set DATE January 2012 @c Use proper quote and backtick for code sections in PDF output @c Cf. Texinfo manual 14.2 @@ -36,7 +36,7 @@ @c orgkey{key} A key item @c orgcmd{key,cmd} Key with command name -@c xorgcmd{key,command} Key with command name as @itemx +@c xorgcmd{key,cmmand} Key with command name as @itemx @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or" @@ -265,7 +265,7 @@ @copying This manual is for Org version @value{VERSION}. -Copyright @copyright{} 2004-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -296,7 +296,7 @@ license to the document, as described in section 6 of the license. @subtitle Release @value{VERSION} @author by Carsten Dominik -with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye +with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K. @c The following two commands start the copyright page. @page @@ -382,7 +382,7 @@ The spreadsheet * Column formulas:: Formulas valid for an entire column * Editing and debugging formulas:: Fixing formulas * Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc +* Advanced features:: Field and column names, parameters and automatic recalc Hyperlinks @@ -433,7 +433,7 @@ Tags Properties and columns * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org-mode features +* Special properties:: Access to other Org mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -462,7 +462,7 @@ Dates and times Creating timestamps -* The date/time prompt:: How Org-mode helps you entering date and time +* The date/time prompt:: How Org mode helps you entering date and time * Custom time format:: Making dates look different Deadlines and scheduling @@ -541,7 +541,7 @@ Markup for rich export * Include files:: Include additional files into a document * Index entries:: Making an index * Macro replacement:: Use macros to create complex output -* Embedded LaTeX:: LaTeX can be freely used inside Org documents +* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents Structural markup elements @@ -560,8 +560,8 @@ Embedded @LaTeX{} * Special symbols:: Greek letters and other symbols * Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Previewing LaTeX fragments:: What will this snippet look like? +* @LaTeX{} fragments:: Complex formulas made easy +* Previewing @LaTeX{} fragments:: What will this snippet look like? * CDLaTeX mode:: Speed up entering of formulas Exporting @@ -571,9 +571,9 @@ Exporting * The export dispatcher:: How to access exporter commands * 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 +* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook -* OpenDocumentText export:: Exporting to OpenDocumentText +* OpenDocument Text export:: Exporting to OpenDocument Text * TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO @@ -583,7 +583,7 @@ HTML export * HTML Export commands:: How to invoke HTML export * HTML preamble and postamble:: How to insert a preamble and a postamble -* Quoting HTML tags:: Using direct HTML in Org-mode +* Quoting HTML tags:: Using direct HTML in Org mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output @@ -594,11 +594,11 @@ HTML export @LaTeX{} and PDF export -* LaTeX/PDF export commands:: Which key invokes which commands +* @LaTeX{}/PDF export commands:: * Header and sectioning:: Setting up the export file structure -* Quoting LaTeX code:: Incorporating literal @LaTeX{} code -* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} -* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code +* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} +* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output * Beamer class export:: Turning the file into a presentation DocBook export @@ -610,15 +610,30 @@ DocBook export * Images in DocBook export:: How to insert figures into DocBook output * Special characters:: How to handle special characters -OpenDocument export +OpenDocument Text export -* OpenDocumentText export commands:: How to invoke OpenDocumentText export -* Applying Custom Styles:: How to apply custom styles to the output -* Converting to Other formats:: How to convert to formats like doc, docx etc -* Links in OpenDocumentText export:: How links will be interpreted and formatted -* Tables in OpenDocumentText export:: How Tables are handled -* Images in OpenDocumentText export:: How to insert figures -* Additional Documentation:: How to handle special characters +* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on +* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export +* Applying custom styles:: How to apply custom styles to the output +* Links in @acronym{ODT} export:: How links will be interpreted and formatted +* Tables in @acronym{ODT} export:: How Tables are exported +* Images in @acronym{ODT} export:: How to insert images +* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted +* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted +* Advanced topics in @acronym{ODT} export:: Read this if you are a power user + +Math formatting in @acronym{ODT} export + +* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments +* Working with MathML or OpenDocument formula files:: How to embed equations in native format + +Advanced topics in @acronym{ODT} export + +* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats +* Working with OpenDocument style files:: Explore the internals +* Creating one-off styles:: How to produce custom highlighting etc +* Customizing tables in @acronym{ODT} export:: How to define and use Table templates +* Validating OpenDocument XML:: How to debug corrupt OpenDocument files Publishing @@ -649,12 +664,12 @@ Working with source code * Editing source code:: Language major-mode editing * Exporting code blocks:: Export contents and/or results * Extracting source code:: Create pure source code files -* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Evaluating code blocks:: Place results of evaluation in the Org mode buffer * Library of Babel:: Use and contribute to a library of useful code blocks * Languages:: List of supported code block languages * Header arguments:: Configure code block functionality * Results of evaluation:: How evaluation results are handled -* Noweb reference syntax:: Literate programming in Org-mode +* Noweb reference syntax:: Literate programming in Org mode * Key bindings and useful functions:: Work quickly with code blocks * Batch execution:: Call functions from the command line @@ -668,7 +683,7 @@ Using header arguments * System-wide header arguments:: Set global default values * Language-specific header arguments:: Set default values by language * Buffer-wide header arguments:: Set default values for a specific buffer -* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Header arguments in Org mode properties:: Set 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 @@ -736,7 +751,7 @@ Hacking Tables and lists in arbitrary syntax * Radio tables:: Sending and receiving radio tables -* A LaTeX example:: Step by step, almost a tutorial +* A @LaTeX{} example:: Step by step, almost a tutorial * Translator functions:: Copy and modify * Radio lists:: Doing the same for lists @@ -898,7 +913,7 @@ make install-info Then add the following line to @file{.emacs}. It is needed so that Emacs can autoload functions that are located in files not immediately loaded -when Org-mode starts. +when Org mode starts. @lisp (require 'org-install) @end lisp @@ -934,9 +949,9 @@ liking. (global-set-key "\C-cb" 'org-iswitchb) @end lisp -@cindex Org-mode, turning on +@cindex Org mode, turning on With this setup, all files with extension @samp{.org} will be put -into Org-mode. As an alternative, make the first line of a file look +into Org mode. As an alternative, make the first line of a file look like this: @example @@ -944,7 +959,7 @@ MY PROJECTS -*- mode: org; -*- @end example @vindex org-insert-mode-line-in-empty-file -@noindent which will select Org-mode for this buffer no matter what +@noindent which will select Org mode for this buffer no matter what the file's name is. See also the variable @code{org-insert-mode-line-in-empty-file}. @@ -987,6 +1002,36 @@ version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org that you only need to add your description. If you re not sending the Email from within Emacs, please copy and paste the content into your Email program. +Sometimes you might face a problem due to an error in your Emacs or Org mode +setup. Before reporting a bug, it is very helpful to start Emacs with minimal +customisations and reproduce the problem. Doing so often helps you determine +if the problem is with your customisation or with Org mode itself. You can +start a typical minimal session with a command like the example below. + +@example +$ emacs -Q -l /path/to/minimal-org.el +@end example + +However if you are using Org mode as distributed with Emacs, a minimal setup +is not necessary. In that case it is sufficient to start Emacs as @code{emacs +-Q}. The @code{minimal-org.el} setup file can have contents as shown below. + +@example +;;; Minimal setup to load latest `org-mode' + +;; activate debugging +(setq debug-on-error t + debug-on-signal nil + debug-on-quit nil) + +;; add latest org-mode to load path +(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) +(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp")) + +;; activate org +(require 'org-install) +@end example + If an error occurs, a backtrace can be very useful (see below on how to create one). Often a small example file helps, along with clear information about: @@ -1009,7 +1054,7 @@ error occurred. Here is how to produce a useful backtrace: @enumerate @item -Reload uncompiled versions of all Org-mode Lisp files. The backtrace +Reload uncompiled versions of all Org mode Lisp files. The backtrace contains much more information if it is produced with uncompiled code. To do this, use @example @@ -1196,8 +1241,8 @@ Reveal context around point, showing the current entry, the following heading and the hierarchy above. Useful for working near a location that has been exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command (@pxref{Agenda commands}). With a prefix argument show, on each -level, all sibling headings. With double prefix arg, also show the entire -subtree of the parent. +level, all sibling headings. With a double prefix argument, also show the +entire subtree of the parent. @orgcmd{C-c C-k,show-branches} Expose all the headings of the subtree, CONTENT view for just one subtree. @orgcmd{C-c C-x b,org-tree-to-indirect-buffer} @@ -1430,7 +1475,7 @@ functionality. @vindex org-show-following-heading @vindex org-show-siblings @vindex org-show-entry-below -An important feature of Org-mode is the ability to construct @emph{sparse +An important feature of Org mode is the ability to construct @emph{sparse trees} for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it@footnote{See also the @@ -1439,7 +1484,7 @@ variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, control on how much context is shown around each match.}. Just try it out and you will see immediately how it works. -Org-mode contains several commands creating such trees, all these +Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: @table @asis @@ -1597,14 +1642,18 @@ to disable them individually. @table @asis @orgcmd{@key{TAB},org-cycle} +@cindex cycling, in plain lists @vindex org-cycle-include-plain-lists Items can be folded just like headline levels. Normally this works only if the cursor is on a plain list item. For more details, see the variable @code{org-cycle-include-plain-lists}. If this variable is set to @code{integrate}, plain list items will be treated like low-level -headlines. The level of an item is then given by the -indentation of the bullet/number. Items are always subordinate to real -headlines, however; the hierarchies remain completely separated. +headlines. The level of an item is then given by the indentation of the +bullet/number. Items are always subordinate to real headlines, however; the +hierarchies remain completely separated. In a new item with no text yet, the +first @key{TAB} demotes the item to become a child of the previous +one. Subsequent @key{TAB}s move the item to meaningful levels in the list +and eventually get it back to its initial position. @orgcmd{M-@key{RET},org-insert-heading} @vindex org-M-RET-may-split-line @vindex org-list-automatic-rules @@ -1615,17 +1664,15 @@ new item@footnote{If you do not want the item to be split, customize the variable @code{org-M-RET-may-split-line}.}. If this command is executed @emph{before item's body}, the new item is created @emph{before} the current one. +@end table + +@table @kbd @kindex M-S-@key{RET} -@item M-S-@key{RET} +@item M-S-RET Insert a new item with a checkbox (@pxref{Checkboxes}). -@orgcmd{@key{TAB},org-cycle} -In a new item with no text yet, the first @key{TAB} demotes the item to -become a child of the previous one. Subsequent @key{TAB}s move the item to -meaningful levels in the list and eventually get it back to its initial -position. @kindex S-@key{down} -@item S-@key{up} -@itemx S-@key{down} +@item S-up +@itemx S-down @cindex shift-selection-mode @vindex org-support-shift-select @vindex org-list-use-circular-motion @@ -1637,21 +1684,21 @@ jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite similar effect. @kindex M-@key{up} @kindex M-@key{down} -@item M-@key{up} -@itemx M-@key{down} +@item M-up +@itemx M-down Move the item including subitems up/down@footnote{See @code{org-liste-use-circular-motion} for a cyclic behavior.} (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic. @kindex M-@key{left} @kindex M-@key{right} -@item M-@key{left} -@itemx M-@key{right} +@item M-left +@itemx M-right Decrease/increase the indentation of an item, leaving children alone. @kindex M-S-@key{left} @kindex M-S-@key{right} -@item M-S-@key{left} -@itemx M-S-@key{right} +@item M-S-left +@itemx M-S-right Decrease/increase the indentation of the item, including subitems. Initially, the item tree is selected based on current indentation. When these commands are executed several times in direct succession, the initially @@ -1694,7 +1741,7 @@ Turn the whole plain list into a subtree of the current heading. Checkboxes (resp. checked). @kindex S-@key{left} @kindex S-@key{right} -@item S-@key{left}/@key{right} +@item S-left/right @vindex org-support-shift-select This command also cycles bullet styles when the cursor in on the bullet or anywhere in an item line, details depending on @@ -1713,7 +1760,7 @@ numerically, alphabetically, by time, or by custom function. @vindex org-drawers Sometimes you want to keep information associated with an entry, but you -normally don't want to see it. For this, Org-mode has @emph{drawers}. +normally don't want to see it. For this, Org mode has @emph{drawers}. Drawers need to be configured with the variable @code{org-drawers}@footnote{You can define drawers on a per-file basis with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers @@ -1731,7 +1778,7 @@ look like this: Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and show the entry, but keep the drawer collapsed to a single line. In order to look inside the drawer, you need to move the cursor to the drawer line and -press @key{TAB} there. Org-mode uses the @code{PROPERTIES} drawer for +press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for storing properties (@pxref{Properties and Columns}), and you can also arrange for state change notes (@pxref{Tracking TODO state changes}) and clock times (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you @@ -1748,7 +1795,7 @@ Add a time-stamped note to the LOGBOOK drawer. @vindex org-hide-block-startup @cindex blocks, folding -Org-mode uses begin...end blocks for various purposes from including source +Org mode uses begin...end blocks for various purposes from including source code examples (@pxref{Literal examples}) to capturing time logging information (@pxref{Clocking work time}). These blocks can be folded and unfolded by pressing TAB in the begin line. You can also get all blocks @@ -1766,8 +1813,8 @@ or on a per-file basis by using @section Footnotes @cindex footnotes -Org-mode supports the creation of footnotes. In contrast to the -@file{footnote.el} package, Org-mode's footnotes are designed for work on a +Org mode supports the creation of footnotes. In contrast to the +@file{footnote.el} package, Org mode's footnotes are designed for work on a larger document, not only for one-off documents like emails. The basic syntax is similar to the one used by @file{footnote.el}, i.e.@: a footnote is defined in a paragraph that is started by a footnote marker in square @@ -1781,11 +1828,11 @@ The Org homepage[fn:1] now looks a lot better than it used to. [fn:1] The link is: http://orgmode.org @end example -Org-mode extends the number-based syntax to @emph{named} footnotes and +Org mode extends the number-based syntax to @emph{named} footnotes and optional inline definition. Using plain numbers as markers (as @file{footnote.el} does) is supported for backward compatibility, but not encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded -LaTeX}). Here are the valid references: +@LaTeX{}}). Here are the valid references: @table @code @item [1] @@ -1875,7 +1922,7 @@ you can use the usual commands to follow these links. @cindex Orgstruct mode @cindex minor mode for structure editing -If you like the intuitive way the Org-mode structure editing and list +If you like the intuitive way the Org mode structure editing and list formatting works, you might want to use these commands in other modes like Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or @@ -2276,7 +2323,7 @@ formula, moving these references by arrow keys * Column formulas:: Formulas valid for an entire column * Editing and debugging formulas:: Fixing formulas * Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc +* Advanced features:: Field and column names, parameters and automatic recalc @end menu @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet @@ -2833,9 +2880,11 @@ dependencies. @node Advanced features, , Updating the table, The spreadsheet @subsection Advanced features -If you want the recalculation of fields to happen automatically, or if -you want to be able to assign @i{names} to fields and columns, you need -to reserve the first column of the table for special marking characters. +If you want the recalculation of fields to happen automatically, or if you +want to be able to assign @i{names}@footnote{Such names must start by an +alphabetic character and use only alphanumeric/underscore characters.} to +fields and columns, you need to reserve the first column of the table for +special marking characters. @table @kbd @orgcmd{C-#,org-table-rotate-recalc-marks} @@ -3005,7 +3054,7 @@ When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a flat mapping rather than a @code{3d} slope. @item timefmt -Specify format of Org-mode timestamps as they will be parsed by Gnuplot. +Specify format of Org mode timestamps as they will be parsed by Gnuplot. Defaults to @samp{%Y-%m-%d-%H:%M:%S}. @item script @@ -3168,11 +3217,19 @@ file:papers/last.pdf @r{file, relative path} ./papers/last.pdf @r{same as above} file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine} /myself@@some.where:papers/last.pdf @r{same as above} -file:sometextfile::NNN @r{file with line number to jump to} +file:sometextfile::NNN @r{file, jump to line number} file:projects.org @r{another Org file} -file:projects.org::some words @r{text search in Org file} +file:projects.org::some words @r{text search in Org file}@footnote{ +The actual behavior of the search will depend on the value of +the variable @code{org-link-search-must-match-exact-headline}. If its value +is nil, then a fuzzy text search will be done. If it is t, then only the +exact headline will be matched. If the value is @code{'query-to-create}, +then an exact headline will be searched; if it is not found, then the user +will be queried to create it.} file:projects.org::*task title @r{heading search in Org file} -docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} +file+sys:/path/to/file @r{open via OS, like double-click} +file+emacs:/path/to/file @r{force opening by Emacs} +docview:papers/last.pdf::NNN @r{open in doc-view mode at page} id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} news:comp.emacs @r{Usenet link} mailto:adent@@galaxy.net @r{Mail link} @@ -3189,7 +3246,7 @@ gnus:group @r{Gnus group link} gnus:group#id @r{Gnus article link} bbdb:R.*Stallman @r{BBDB link (with regexp)} irc:/irc.com/#emacs/bob @r{IRC link} -info:org#External%20links @r{Info node link (with encoded space)} +info:org#External links @r{Info node link} shell:ls *.org @r{A shell command} elisp:org-agenda @r{Interactive Elisp command} elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} @@ -3235,7 +3292,7 @@ create a link. The link will be stored for later insertion into an Org buffer (see below). What kind of link will be created depends on the current buffer: -@b{Org-mode buffers}@* +@b{Org mode buffers}@* For Org files, if there is a @samp{<<target>>} at the cursor, the link points to the target. Otherwise it points to the current headline, which will also be the description@footnote{If the headline contains a timestamp, it will be @@ -3338,6 +3395,7 @@ link and description parts of the link. @cindex following links @orgcmd{C-c C-o,org-open-at-point} @vindex org-file-apps +@vindex org-link-frame-setup Open link at point. This will launch a web browser for URLs (using @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for the corresponding links, and execute the command in a shell link. When the @@ -3351,7 +3409,9 @@ Classification of files is based on file extension only. See option visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid opening in Emacs, use a @kbd{C-u C-u} prefix.@* If the cursor is on a headline, but not on a link, offer all links in the -headline and entry text. +headline and entry text. If you want to setup the frame configuration for +following links, customize @code{org-link-frame-setup}. + @orgkey @key{RET} @vindex org-return-follows-link When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow @@ -3525,7 +3585,7 @@ Link to a heading with a @code{CUSTOM_ID} property @item /regexp/ Do a regular expression search for @code{regexp}. This uses the Emacs command @code{occur} to list all matches in a separate window. If the -target file is in Org-mode, @code{org-occur} is used to create a +target file is in Org mode, @code{org-occur} is used to create a sparse tree with the matches. @c If the target file is a directory, @c @code{grep} will be used to search all files in the directory. @@ -3564,7 +3624,7 @@ an implementation example. See the file @file{org-bibtex.el}. @chapter TODO items @cindex TODO items -Org-mode does not maintain TODO lists as separate documents@footnote{Of +Org mode does not maintain TODO lists as separate documents@footnote{Of course, you can make a document that contains only long lists of TODO items, but this is not required.}. Instead, TODO items are an integral part of the notes file, because TODO items usually come up while taking notes! With Org @@ -3573,7 +3633,7 @@ information is not duplicated, and the entire context from which the TODO item emerged is always present. Of course, this technique for managing TODO items scatters them -throughout your notes file. Org-mode compensates for this by providing +throughout your notes file. Org mode compensates for this by providing methods to give you an overview of all the things that you have to do. @menu @@ -3659,7 +3719,7 @@ option @code{org-todo-state-tags-triggers} for details. @vindex org-todo-keywords By default, marked TODO entries have one of only two states: TODO and -DONE. Org-mode allows you to classify TODO items in more complex ways +DONE. Org mode allows you to classify TODO items in more complex ways with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With special setup, the TODO keyword system can work differently in different files. @@ -3684,7 +3744,7 @@ TODO items in particular (@pxref{Tags}). You can use TODO keywords to indicate different @emph{sequential} states in the process of working on an item, for example@footnote{Changing -this variable only becomes effective after restarting Org-mode in a +this variable only becomes effective after restarting Org mode in a buffer.}: @lisp @@ -3727,7 +3787,7 @@ be set up like this: In this case, different keywords do not indicate a sequence, but rather different types. So the normal work flow would be to assign a task to a -person, and later to mark it DONE. Org-mode supports this style by adapting +person, and later to mark it DONE. Org mode supports this style by adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true for the @kbd{t} command in the timeline and agenda buffers.}. When used several times in succession, it will still cycle through all names, in order to first @@ -3758,7 +3818,7 @@ like this: (sequence "|" "CANCELED"))) @end lisp -The keywords should all be different, this helps Org-mode to keep track +The keywords should all be different, this helps Org mode to keep track of which subsequence should be used for a given entry. In this setup, @kbd{C-c C-t} only operates within a subsequence, so it switches from @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to @@ -3855,9 +3915,9 @@ Remember that the keywords after the vertical bar (or the last keyword if no bar is there) must always mean that the item is DONE (although you may use a different word). After changing one of these lines, use @kbd{C-c C-c} with the cursor still in the line to make the changes -known to Org-mode@footnote{Org-mode parses these lines only when -Org-mode is activated after visiting a file. @kbd{C-c C-c} with the -cursor in a line starting with @samp{#+} is simply restarting Org-mode +known to Org mode@footnote{Org mode parses these lines only when +Org mode is activated after visiting a file. @kbd{C-c C-c} with the +cursor in a line starting with @samp{#+} is simply restarting Org mode for the current buffer.}. @node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions @@ -3867,7 +3927,7 @@ for the current buffer.}. @vindex org-todo @r{(face)} @vindex org-done @r{(face)} @vindex org-todo-keyword-faces -Org-mode highlights TODO keywords with special faces: @code{org-todo} +Org mode highlights TODO keywords with special faces: @code{org-todo} for keywords indicating that an item still has to be acted upon, and @code{org-done} for keywords indicating that an item is finished. If you are using more than 2 different states, you might want to use @@ -3883,7 +3943,7 @@ special faces for some of them. This can be done using the variable @end lisp While using a list with face properties as shown for CANCELED @emph{should} -work, this does not always seem to be the case. If necessary, define a +work, this does not aways seem to be the case. If necessary, define a special face and use that. A string is interpreted as a color. The variable @code{org-faces-easy-properties} determines if that color is interpreted as a foreground or a background color. @@ -3955,7 +4015,7 @@ module @file{org-depend.el}. @cindex progress logging @cindex logging, of progress -Org-mode can automatically record a timestamp and possibly a note when +Org mode can automatically record a timestamp and possibly a note when you mark a TODO item as DONE, or even each time you change the state of a TODO item. This system is highly configurable, settings can be on a per-keyword basis and can be localized to a file or even a subtree. For @@ -4019,21 +4079,25 @@ behavior---the recommended drawer for this is called @code{LOGBOOK}. You can also overrule the setting of this variable for a subtree by setting a @code{LOG_INTO_DRAWER} property. -Since it is normally too much to record a note for every state, Org-mode +Since it is normally too much to record a note for every state, Org mode expects configuration on a per-keyword basis for this. This is achieved by -adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note) -in parentheses after each keyword. For example, with the setting +adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note +with timestamp) in parentheses after each keyword. For example, with the +setting @lisp (setq org-todo-keywords '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)"))) @end lisp +To record a timestamp without a note for TODO keywords configured with +@samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted. + @noindent @vindex org-log-done you not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to -DONE@footnote{It is possible that Org-mode will record two timestamps +DONE@footnote{It is possible that Org mode will record two timestamps when you are using both @code{org-log-done} and state change logging. However, it will never prompt for two notes---if you have configured both, the state change recording note will take precedence and cancel @@ -4182,7 +4246,7 @@ which should only be done in certain contexts, for example. @section Priorities @cindex priorities -If you use Org-mode extensively, you may end up with enough TODO items that +If you use Org mode extensively, you may end up with enough TODO items that it starts to make sense to prioritize them. Prioritizing can be done by placing a @emph{priority cookie} into the headline of a TODO item, like this @@ -4192,11 +4256,11 @@ placing a @emph{priority cookie} into the headline of a TODO item, like this @noindent @vindex org-priority-faces -By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and +By default, Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry without a cookie is treated just like priority @samp{B}. Priorities make a difference only for sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they -have no inherent meaning to Org-mode. The cookies can be highlighted with +have no inherent meaning to Org mode. The cookies can be highlighted with special faces by customizing the variable @code{org-priority-faces}. Priorities can be attached to any outline node; they do not need to be TODO @@ -4363,9 +4427,11 @@ off a box while there are unchecked boxes above it. @table @kbd @orgcmd{C-c C-c,org-toggle-checkbox} -Toggle checkbox status or (with prefix arg) checkbox presence at point. With -double prefix argument, set it to @samp{[-]}, which is considered to be an -intermediate state. +Toggle checkbox status or (with prefix arg) checkbox presence at point. +With a single prefix argument, add an empty checkbox or remove the current +one@footnote{`C-u C-c C-c' on the @emph{first} item of a list with no checkbox +will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is +considered to be an intermediate state. @orgcmd{C-c C-x C-b,org-toggle-checkbox} Toggle checkbox status or (with prefix arg) checkbox presence at point. With double prefix argument, set it to @samp{[-]}, which is considered to be an @@ -4410,7 +4476,7 @@ hand, use this command to get things back into sync. @cindex sparse tree, tag based An excellent way to implement labels and contexts for cross-correlating -information is to assign @i{tags} to headlines. Org-mode has extensive +information is to assign @i{tags} to headlines. Org mode has extensive support for tags. @vindex org-tag-faces @@ -4489,7 +4555,7 @@ also a special command for inserting tags: @orgcmd{C-c C-q,org-set-tags-command} @cindex completion, of tags @vindex org-tags-column -Enter new tags for the current headline. Org-mode will either offer +Enter new tags for the current headline. Org mode will either offer completion or a special single-key interface for setting tags, see below. After pressing @key{RET}, the tags will be inserted and aligned to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all @@ -4532,7 +4598,7 @@ by adding a STARTUP option line to that file: #+STARTUP: noptag @end example -By default Org-mode uses the standard minibuffer completion facilities for +By default Org mode uses the standard minibuffer completion facilities for entering tags. However, it also implements another, quicker, tag selection method called @emph{fast tag selection}. This allows you to select and deselect tags with just a single key press. For this to work well you should @@ -4691,25 +4757,26 @@ and properties. For a complete description with many examples, see @chapter Properties and columns @cindex properties -Properties are a set of key-value pairs associated with an entry. There -are two main applications for properties in Org-mode. First, properties -are like tags, but with a value. Second, you can use properties to -implement (very basic) database capabilities in an Org buffer. For -an example of the first application, imagine maintaining a file where +A property is a key-value pair associated with an entry. Properties can be +set so they are associated with a single entry, with every entry in a tree, +or with every entry in an Org mode file. + +There are two main applications for properties in Org mode. First, +properties are like tags, but with a value. Imagine maintaining a file where you document bugs and plan releases for a piece of software. Instead of -using tags like @code{:release_1:}, @code{:release_2:}, one can use a +using tags like @code{:release_1:}, @code{:release_2:}, you can use a property, say @code{:Release:}, that in different subtrees has different -values, such as @code{1.0} or @code{2.0}. For an example of the second -application of properties, imagine keeping track of your music CDs, -where properties could be things such as the album, artist, date of -release, number of tracks, and so on. +values, such as @code{1.0} or @code{2.0}. Second, you can use properties to +implement (very basic) database capabilities in an Org buffer. Imagine +keeping track of your music CDs, where properties could be things such as the +album, artist, date of release, number of tracks, and so on. Properties can be conveniently edited and viewed in column view (@pxref{Column view}). @menu * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org-mode features +* Special properties:: Access to other Org mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -4721,7 +4788,8 @@ Properties can be conveniently edited and viewed in column view @cindex property syntax @cindex drawer, for properties -Properties are key-value pairs. They need to be inserted into a special +Properties are key-value pairs. When they are associated with a single entry +or with a tree they need to be inserted into a special drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property is specified on a single line, with the key (surrounded by colons) first, and the value after it. Here is an example: @@ -4739,6 +4807,10 @@ first, and the value after it. Here is an example: :END: @end example +Depending on the value of @code{org-use-property-inheritance}, a property set +this way will either be associated with a single entry, or the sub-tree +defined by the entry, see @ref{Property inheritance}. + You may define the allowed values for a particular property @samp{:Xyz:} by setting a property @samp{:Xyz_ALL:}. This special property is @emph{inherited}, so if you set it in a level 1 entry, it will apply to @@ -4763,6 +4835,37 @@ file, use a line like #+PROPERTY: NDisks_ALL 1 2 3 4 @end example +If you want to add to the value of an existing property, append a @code{+} to +the property name. The following results in the property @code{var} having +the value ``foo=1 bar=2''. +@cindex property, + +@example +#+PROPERTY: var foo=1 +#+PROPERTY: var+ bar=2 +@end example + +It is also possible to add to the values of inherited properties. The +following results in the @code{genres} property having the value ``Classic +Baroque'' under the @code{Goldberg Variations} subtree. +@cindex property, + +@example +* CD collection +** Classic + :PROPERTIES: + :GENRES: Classic + :END: +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Artist: Glen Gould + :Publisher: Deutsche Grammophon + :NDisks: 1 + :GENRES+: Baroque + :END: +@end example +Note that a property can only have one entry per Drawer. + @vindex org-global-properties Property values set with the global variable @code{org-global-properties} can be inherited by all entries in all @@ -4803,7 +4906,7 @@ nearest column format definition. @section Special properties @cindex properties, special -Special properties provide an alternative access method to Org-mode features, +Special properties provide an alternative access method to Org mode features, like the TODO state or the priority of an entry, discussed in the previous chapters. This interface exists so that you can include these states in a column view (@pxref{Column view}), or to use them in queries. The following @@ -4885,9 +4988,9 @@ a regular expression and matched against the property values. @cindex inheritance, of properties @vindex org-use-property-inheritance -The outline structure of Org-mode documents lends itself to an +The outline structure of Org mode documents lends itself to an inheritance model of properties: if the parent in a tree has a certain -property, the children can inherit this property. Org-mode does not +property, the children can inherit this property. Org mode does not turn this on by default, because it can slow down property searches significantly and is often not needed. However, if you find inheritance useful, you can turn it on by setting the variable @@ -4898,7 +5001,7 @@ inherited properties. If a property has the value @samp{nil}, this is interpreted as an explicit undefine of the property, so that inheritance search will stop at this value and return @code{nil}. -Org-mode has a few properties for which inheritance is hard-coded, at +Org mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used: @cindex property, COLUMNS @@ -4929,7 +5032,7 @@ subtree (@pxref{Tracking TODO state changes}). A great way to view and edit properties in an outline tree is @emph{column view}. In column view, each outline node is turned into a table row. Columns in this table provide access to properties of the -entries. Org-mode implements columns by overlaying a tabular structure +entries. Org mode implements columns by overlaying a tabular structure over the headline of each item. While the headlines have been turned into a table row, you can still change the visibility of the outline tree. For example, you get a compact table by switching to CONTENTS @@ -5231,9 +5334,9 @@ property API}. To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and time -information is called a @emph{timestamp} in Org-mode. This may be a +information is called a @emph{timestamp} in Org mode. This may be a little confusing because timestamp is often used as indicating when -something was created or last changed. However, in Org-mode this term +something was created or last changed. However, in Org mode this term is used in a much wider sense. @menu @@ -5256,17 +5359,20 @@ is used in a much wider sense. @cindex scheduling A timestamp is a specification of a date (possibly with a time or a range of -times) in a special format, either @samp{<2003-09-16 Tue>} or -@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue -12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 date/time -format. To use an alternative format, see @ref{Custom time format}.}. A -timestamp can appear anywhere in the headline or body of an Org tree entry. -Its presence causes entries to be shown on specific dates in the agenda -(@pxref{Weekly/daily agenda}). We distinguish: +times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this +simplest form, the day name is optional when you type the date yourself. +However, any dates inserted or modified by Org will add that day name, for +reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 +Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 +date/time format. To use an alternative format, see @ref{Custom time +format}.}. A timestamp can appear anywhere in the headline or body of an Org +tree entry. Its presence causes entries to be shown on specific dates in the +agenda (@pxref{Weekly/daily agenda}). We distinguish: @table @var @item Plain timestamp; Event; Appointment @cindex timestamp +@cindex appointment A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. In the timeline and agenda displays, the headline of an entry associated with a @@ -5289,7 +5395,7 @@ following will show up in the agenda every Wednesday: @end example @item Diary-style sexp entries -For more complex date specifications, Org-mode supports using the special +For more complex date specifications, Org mode supports using the special sexp diary entries implemented in the Emacs calendar/diary package@footnote{When working with the standard diary sexp functions, you need to be very careful with the order of the arguments. That order depend @@ -5297,7 +5403,7 @@ evilly on the variable @code{calendar-date-style} (or, for older Emacs versions, @code{european-calendar-style}). For example, to specify a date December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on -the settings. This has been the source of much confusion. Org-mode users +the settings. This has been the source of much confusion. Org mode users can resort to special versions of these functions like @code{org-date} or @code{org-anniversary}. These work just like the corresponding @code{diary-} functions, but with stable ISO order of arguments (year, month, day) wherever @@ -5338,7 +5444,7 @@ angular ones. These timestamps are inactive in the sense that they do @cindex creating timestamps @cindex timestamps, creating -For Org-mode to recognize timestamps, they need to be in the specific +For Org mode to recognize timestamps, they need to be in the specific format. All commands listed below produce timestamps in the correct format. @@ -5362,6 +5468,9 @@ Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which contains date and time. The default time can be rounded to multiples of 5 minutes, see the option @code{org-time-stamp-rounding-minutes}. @c +@orgkey{C-c C-c} +Normalize timestamp, insert/fix day name if missing or wrong. +@c @orgcmd{C-c <,org-date-from-calendar} Insert a timestamp corresponding to the cursor date in the Calendar. @c @@ -5397,7 +5506,7 @@ the following column). @menu -* The date/time prompt:: How Org-mode helps you entering date and time +* The date/time prompt:: How Org mode helps you entering date and time * Custom time format:: Making dates look different @end menu @@ -5407,17 +5516,17 @@ the following column). @cindex time, reading in minibuffer @vindex org-read-date-prefer-future -When Org-mode prompts for a date/time, the default is shown in default +When Org mode prompts for a date/time, the default is shown in default date/time format, and the prompt therefore seems to ask for a specific format. But it will in fact accept any string containing some date and/or time information, and it is really smart about interpreting your input. You can, for example, use @kbd{C-y} to paste a (possibly multi-line) string -copied from an email message. Org-mode will find whatever information is in +copied from an email message. Org mode will find whatever information is in there and derive anything you have not specified from the @emph{default date and time}. The default is usually the current date and time, but when modifying an existing timestamp, or when entering the second stamp of a range, it is taken from the stamp in the buffer. When filling in -information, Org-mode assumes that most of the time you will want to enter a +information, Org mode assumes that most of the time you will want to enter a date in the future: if you omit the month/year and the given day/month is @i{before} today, it will assume that you mean a future date@footnote{See the variable @code{org-read-date-prefer-future}. You may set that variable to @@ -5426,7 +5535,7 @@ tomorrow.}. If the date has been automatically shifted into the future, the time prompt will show this with @samp{(=>F).} For example, let's assume that today is @b{June 13, 2006}. Here is how -various inputs will be interpreted, the items filled in by Org-mode are +various inputs will be interpreted, the items filled in by Org mode are in @b{bold}. @example @@ -5536,7 +5645,7 @@ minibuffer@footnote{If you find this distracting, turn the display of with @vindex org-display-custom-times @vindex org-time-stamp-custom-formats -Org-mode uses the standard ISO notation for dates and times as it is +Org mode uses the standard ISO notation for dates and times as it is defined in ISO 8601. If you cannot get used to this and require another representation of date and time to keep you happy, you can get it by customizing the variables @code{org-display-custom-times} and @@ -5548,7 +5657,7 @@ Toggle the display of custom formats for dates and times. @end table @noindent -Org-mode needs the default format for scanning, so the custom date/time +Org mode needs the default format for scanning, so the custom date/time format does not @emph{replace} the default format---instead it is put @emph{over} the default format using text properties. This has the following consequences: @@ -5625,23 +5734,23 @@ the task will automatically be forwarded until completed. @end example @noindent -@b{Important:} Scheduling an item in Org-mode should @i{not} be +@b{Important:} Scheduling an item in Org mode should @i{not} be understood in the same way that we understand @i{scheduling a meeting}. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by -Org users. In Org-mode, @i{scheduling} means setting a date when you +Org users. In Org mode, @i{scheduling} means setting a date when you want to start working on an action item. @end table You may use timestamps with repeaters in scheduling and deadline -entries. Org-mode will issue early and late warnings based on the +entries. Org mode will issue early and late warnings based on the assumption that the timestamp represents the @i{nearest instance} of the repeater. However, the use of diary sexp entries like @c @code{<%%(org-float t 42)>} @c -in scheduling and deadline timestamps is limited. Org-mode does not +in scheduling and deadline timestamps is limited. Org mode does not know enough about the internals of each sexp function to issue early and late warnings. However, it will show the item on each day where the sexp entry matches. @@ -5714,7 +5823,7 @@ to the previous week before any current timestamp. @cindex tasks, repeated @cindex repeated tasks -Some tasks need to be repeated again and again. Org-mode helps to +Some tasks need to be repeated again and again. Org mode helps to organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, or plain timestamp. In the following example @example @@ -5734,7 +5843,7 @@ over-due, so it is important to be able to mark such an entry as completed once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO keyword DONE, it will no longer produce entries in the agenda. The problem with this is, however, that then also the @emph{next} instance of the -repeated entry will not be active. Org-mode deals with this in the following +repeated entry will not be active. Org mode deals with this in the following way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating timestamp by the repeater interval, and immediately set the entry state back to TODO@footnote{In fact, the target @@ -5767,7 +5876,7 @@ task, this may not be the best way to handle it. For example, if you forgot to call your father for 3 weeks, it does not make sense to call him 3 times in a single day to make up for it. Finally, there are tasks like changing batteries which should always repeat a certain time -@i{after} the last time you did it. For these tasks, Org-mode has +@i{after} the last time you did it. For these tasks, Org mode has special repeaters @samp{++} and @samp{.+}. For example: @example @@ -5796,7 +5905,7 @@ created for this purpose, it is described in @ref{Structure editing}. @cindex clocking time @cindex time clocking -Org-mode allows you to clock the time you spend on specific tasks in a +Org mode allows you to clock the time you spend on specific tasks in a project. When you start working on an item, you can start the clock. When you stop working on that task, or when you mark the task done, the clock is stopped and the corresponding time interval is recorded. It @@ -5915,10 +6024,11 @@ formatted as one or several Org tables. @table @kbd @orgcmd{C-c C-x C-r,org-clock-report} Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock -report as an Org-mode table into the current file. When the cursor is +report as an Org mode table into the current file. When the cursor is at an existing clock table, just update it. When called with a prefix argument, jump to the first clock report in the current document and -update it. +update it. The clock table always includes also trees with +@code{:ARCHIVE:} tag. @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} Update dynamic block at point. The cursor needs to be in the @code{#+BEGIN} line of the dynamic block. @@ -6215,8 +6325,8 @@ not started at exactly the right moment. @kindex C-c C-x ; @kindex ; -Calling @code{org-timer-set-timer} from an Org-mode buffer runs a countdown -timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everywhere else. +Calling @code{org-timer-set-timer} from an Org mode buffer runs a countdown +timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everwhere else. @code{org-timer-set-timer} prompts the user for a duration and displays a countdown timer in the modeline. @code{org-timer-default-timer} sets the @@ -6249,7 +6359,7 @@ trees to an archive file keeps the system compact and fast. Org's method for capturing new items is heavily inspired by John Wiegley excellent remember package. Up to version 6.36 Org used a special setup -for @file{remember.el}. @file{org-remember.el} is still part of Org-mode for +for @file{remember.el}. @file{org-remember.el} is still part of Org mode for backward compatibility with existing setups. You can find the documentation for org-remember at @url{http://orgmode.org/org-remember.pdf}. @@ -6393,7 +6503,7 @@ like this: @node Template elements, Template expansion, Capture templates, Capture templates @subsubsection Template elements -Now let's look at the elements of a template definition. Each entry in +Now lets look at the elements of a template definition. Each entry in @code{org-capture-templates} is a list with the following items: @table @var @@ -6418,8 +6528,8 @@ selection. The type of entry, a symbol. Valid values are: @table @code @item entry -An Org-mode node, with a headline. Will be filed as the child of the target -entry or as a top-level entry. The target file should be an Org-mode file. +An Org mode node, with a headline. Will be filed as the child of the target +entry or as a top-level entry. The target file should be an Org mode file. @item item A plain list item, placed in the first plain list at the target location. Again the target file should be an Org file. @@ -6436,7 +6546,7 @@ Text to be inserted as it is. @item target @vindex org-default-notes-file -Specification of where the captured item should be placed. In Org-mode +Specification of where the captured item should be placed. In Org mode files, targets usually define a node. Entries will become children of this node. Other types will be added to the table or list in the body of this node. Most target specifications contain a file name. If that file name is @@ -6536,7 +6646,7 @@ buffer again after capture is completed. In the template itself, special @kbd{%}-escapes@footnote{If you need one of these sequences literally, escape the @kbd{%} with a backslash.} allow -dynamic insertion of content. The templates are expanded in the order given here: +dynamic insertion of content. The templates are expanded in the order given here: @smallexample %[@var{file}] @r{insert the contents of the file given by @var{file}.} @@ -7032,6 +7142,7 @@ the front. With a prefix argument, file is added/moved to the end. @orgcmd{C-c ],org-remove-file} Remove current file from the list of agenda files. @kindex C-, +@cindex cycling, of agenda files @orgcmd{C-',org-cycle-agenda-files} @itemx C-, Cycle through agenda file list, visiting one file after the other. @@ -7187,7 +7298,7 @@ anniversaries, lunar phases, sunrise/set, recurrent appointments Org. It can be very useful to combine output from Org with the diary. -In order to include entries from the Emacs diary into Org-mode's +In order to include entries from the Emacs diary into Org mode's agenda, you only need to customize the variable @lisp @@ -7196,7 +7307,7 @@ agenda, you only need to customize the variable @noindent After that, everything will happen automatically. All diary entries including holidays, anniversaries, etc., will be included in the -agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and +agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and @key{RET} can be used from the agenda buffer to jump to the diary file in order to edit existing diary entries. The @kbd{i} command to insert new entries for the current date works in the agenda buffer, as @@ -7207,7 +7318,7 @@ between calendar and agenda. If you are using the diary only for sexp entries and holidays, it is faster to not use the above setting, but instead to copy or even move -the entries into an Org file. Org-mode evaluates diary-style sexp +the entries into an Org file. Org mode evaluates diary-style sexp entries, and does it faster because there is no overhead for first creating the diary display. Note that the sexp entries must start at the left margin, no whitespace is allowed before them. For example, @@ -7253,7 +7364,7 @@ followed by a space and the class of the anniversary (@samp{birthday} or 1973-06-22 06-22 1955-08-02 wedding -2008-04-14 %s released version 6.01 of org-mode, %d years ago +2008-04-14 %s released version 6.01 of org mode, %d years ago @end example After a change to BBDB, or for the first agenda display during an Emacs @@ -7265,6 +7376,8 @@ in an Org or Diary file. @subsubheading Appointment reminders @cindex @file{appt.el} @cindex appointment reminders +@cindex appointment +@cindex reminders Org can interact with Emacs appointments notification facility. To add all the appointments of your agenda files, use the command @@ -7466,7 +7579,7 @@ other properties will slow down the search. However, once you have paid the price by accessing one property, testing additional properties is cheap again. -You can configure Org-mode to use property inheritance during a search, but +You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See @ref{Property inheritance}, for details. @@ -7499,7 +7612,7 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or @cindex timeline, single file @cindex time-sorted view -The timeline summarizes all time-stamped items from a single Org-mode +The timeline summarizes all time-stamped items from a single Org mode file in a @emph{time-sorted view}. The main purpose of this command is to give an overview over events in a project. @@ -7520,7 +7633,7 @@ The commands available in the timeline buffer are listed in @cindex text search @cindex searching, for text -This agenda view is a general text search facility for Org-mode entries. +This agenda view is a general text search facility for Org mode entries. It is particularly useful to find notes. @table @kbd @@ -7552,7 +7665,7 @@ If you are following a system like David Allen's GTD to organize your work, one of the ``duties'' you have is a regular review to make sure that all projects move along. A @emph{stuck} project is a project that has no defined next actions, so it will never show up in the TODO lists -Org-mode produces. During the review, you need to identify such +Org mode produces. During the review, you need to identify such projects and define next actions for them. @table @kbd @@ -7570,7 +7683,7 @@ work for you. The built-in default assumes that all your projects are level-2 headlines, and that a project is not stuck if it has at least one entry marked with a TODO keyword TODO or NEXT or NEXTACTION. -Let's assume that you, in your own way of using Org-mode, identify +Let's assume that you, in your own way of using Org mode, identify projects with a tag PROJECT, and that you use a TODO keyword MAYBE to indicate a project that should not be considered yet. Let's further assume that the TODO keyword DONE marks finished projects, and that NEXT @@ -7598,7 +7711,7 @@ will still be searched for stuck projects. @vindex org-agenda-prefix-format @vindex org-agenda-tags-column -Before displaying items in an agenda view, Org-mode visually prepares the +Before displaying items in an agenda view, Org mode visually prepares the items and sorts them. Each item occupies a single line. The line starts with a @emph{prefix} that contains the @emph{category} (@pxref{Categories}) of the item and other important information. You can customize in which @@ -7651,7 +7764,7 @@ You can set up icons for category by customizing the @subsection Time-of-day specifications @cindex time-of-day specification -Org-mode checks each agenda item for a time-of-day specification. The +Org mode checks each agenda item for a time-of-day specification. The time can be part of the timestamp that triggered inclusion into the agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time ranges can be specified with two timestamps, like @@ -7663,7 +7776,7 @@ plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda integrates the Emacs diary (@pxref{Weekly/daily agenda}), time specifications in diary entries are recognized as well. -For agenda display, Org-mode extracts the time and displays it in a +For agenda display, Org mode extracts the time and displays it in a standard 24 hour format as part of the prefix. The example times in the previous paragraphs would end up in the agenda like this: @@ -7861,6 +7974,7 @@ press @kbd{v a} again. @c @orgcmdkskc{v R,R,org-agenda-clockreport-mode} @vindex org-agenda-start-with-clockreport-mode +@vindex org-clock-report-include-clocking-task Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will always show a table with the clocked times for the timespan and file scope covered by the current agenda view. The initial setting for this mode in new @@ -7868,7 +7982,8 @@ agenda buffers can be set with the variable @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show contributions from entries that are hidden by agenda filtering@footnote{Only -tags filtering will be respected here, effort filtering is ignored.}. +tags filtering will be respected here, effort filtering is ignored.}. See +also the variable @code{org-clock-report-include-clocking-task}. @c @orgkey{v c} @vindex org-agenda-clock-consistency-checks @@ -7921,18 +8036,27 @@ Remove the restriction lock on the agenda, if it is currently restricted to a file or subtree (@pxref{Agenda files}). @tsubheading{Secondary filtering and query editing} -@cindex filtering, by tag and effort, in agenda +@cindex filtering, by tag category and effort, in agenda @cindex tag filtering, in agenda +@cindex category filtering, in agenda @cindex effort filtering, in agenda @cindex query editing, in agenda +@orgcmd{<,org-agenda-filter-by-category} +@vindex org-agenda-category-filter-preset + +Filter the current agenda view with respect to the category of the item at +point. Pressing @code{<} another time will remove this filter. You can add +a filter preset through the option @code{org-agenda-category-filter-preset} +(see below.) + @orgcmd{/,org-agenda-filter-by-tag} -@vindex org-agenda-filter-preset +@vindex org-agenda-tag-filter-preset Filter the current agenda view with respect to a tag and/or effort estimates. The difference between this and a custom agenda command is that filtering is very fast, so that you can switch quickly between different filters without having to recreate the agenda.@footnote{Custom commands can preset a filter by -binding the variable @code{org-agenda-filter-preset} as an option. This +binding the variable @code{org-agenda-tag-filter-preset} as an option. This filter will then be applied to the view and persist as a basic filter through refreshes and more secondary filtering. The filter is a global property of the entire agenda view---in a block agenda, you should only set this in the @@ -8076,7 +8200,7 @@ agenda, change a tag for all headings in the region. @kindex , @item , Set the priority for the current item (@command{org-agenda-priority}). -Org-mode prompts for the priority character. If you reply with @key{SPC}, +Org mode prompts for the priority character. If you reply with @key{SPC}, the priority cookie is removed from the entry. @c @orgcmd{P,org-agenda-show-priority} @@ -8122,13 +8246,15 @@ command. @c @orgcmd{S-@key{right},org-agenda-do-date-later} Change the timestamp associated with the current line by one day into the -future. With a numeric prefix argument, change it by that many days. For -example, @kbd{3 6 5 S-@key{right}} will change it by a year. With a -@kbd{C-u} prefix, change the time by one hour. If you immediately repeat the -command, it will continue to change hours even without the prefix arg. With -a double @kbd{C-u C-u} prefix, do the same for changing minutes. The stamp -is changed in the original Org file, but the change is not directly reflected -in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer. +future. If the date is in the past, the first call to this command will move +it to today.@* +With a numeric prefix argument, change it by that many days. For example, +@kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix, +change the time by one hour. If you immediately repeat the command, it will +continue to change hours even without the prefix arg. With a double @kbd{C-u +C-u} prefix, do the same for changing minutes.@* +The stamp is changed in the original Org file, but the change is not directly +reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer. @c @orgcmd{S-@key{left},org-agenda-do-date-earlier} Change the timestamp associated with the current line by one day @@ -8213,7 +8339,7 @@ f @r{Apply a function to marked entries.} Open the Emacs calendar and move to the date at the agenda cursor. @c @orgcmd{c,org-calendar-goto-agenda} -When in the calendar, compute and show the Org-mode agenda for the +When in the calendar, compute and show the Org mode agenda for the date at the cursor. @c @cindex diary entries, creating from agenda @@ -8226,8 +8352,8 @@ file@footnote{This file is parsed for the agenda when command in the calendar. The diary file will pop up in another window, where you can add the entry. -If you configure @code{org-agenda-diary-file} to point to an Org-mode file, -Org will create entries (in org-mode syntax) in that file instead. Most +If you configure @code{org-agenda-diary-file} to point to an Org mode file, +Org will create entries (in Org mode syntax) in that file instead. Most entries will be stored in a date-based outline tree that will later make it easy to archive appointments from previous months/years. The tree will be built under an entry with a @code{DATE_TREE} property, or else with years as @@ -8262,7 +8388,7 @@ This is a globally available command, and also available in the agenda menu. @vindex org-agenda-exporter-settings Write the agenda view to a file. Depending on the extension of the selected file name, the view will be exported as HTML (extension @file{.html} or -@file{.htm}), PostScript (extension @file{.ps}), PDF (extension @file{.pdf}), +@file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}), and plain text (any other extension). When called with a @kbd{C-u} prefix argument, immediately open the newly created file. Use the variable @code{org-agenda-exporter-settings} to set options for @file{ps-print} and @@ -8403,7 +8529,7 @@ command @kbd{C-c a o} provides a similar view for office tasks. @cindex options, for custom agenda views @vindex org-agenda-custom-commands -Org-mode contains a number of variables regulating agenda construction +Org mode contains a number of variables regulating agenda construction and display. The global variables define the behavior for all agenda commands, including the custom commands. However, if you want to change some settings just for a single custom view, you can do so. Setting @@ -8475,11 +8601,11 @@ yourself. @cindex agenda views, exporting If you are away from your computer, it can be very useful to have a printed -version of some agenda views to carry around. Org-mode can export custom +version of some agenda views to carry around. Org mode can export custom agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's -@file{htmlize.el}.}, PostScript, PDF@footnote{To create PDF output, the +@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the ghostscript @file{ps2pdf} utility must be installed on the system. Selecting -a PDF file will also create the PostScript file.}, and iCalendar files. If +a PDF file will also create the postscript file.}, and iCalendar files. If you want to do this only occasionally, use the command @table @kbd @@ -8489,7 +8615,7 @@ you want to do this only occasionally, use the command @vindex org-agenda-exporter-settings Write the agenda view to a file. Depending on the extension of the selected file name, the view will be exported as HTML (extension @file{.html} or -@file{.htm}), PostScript (extension @file{.ps}), iCalendar (extension +@file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension @file{.ics}), or plain text (any other extension). Use the variable @code{org-agenda-exporter-settings} to set options for @file{ps-print} and for @file{htmlize} to be used during export, for example @@ -8539,10 +8665,10 @@ or absolute. @end lisp The extension of the file name determines the type of export. If it is -@file{.html}, Org-mode will use the @file{htmlize.el} package to convert +@file{.html}, Org mode will use the @file{htmlize.el} package to convert the buffer to HTML and save it to this file name. If the extension is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce -PostScript output. If the extension is @file{.ics}, iCalendar export is +Postscript output. If the extension is @file{.ics}, iCalendar export is run export over all files that were used to construct the agenda, and limit the export to entries listed in the agenda. Any other extension produces a plain ASCII file. @@ -8573,7 +8699,7 @@ set options for the export commands. For example: @end lisp @noindent -This command sets two options for the PostScript exporter, to make it +This command sets two options for the Postscript exporter, to make it print in two columns in landscape format---the resulting page can be cut in two and then used in a paper agenda. The remaining settings modify the agenda prefix to omit category and scheduling information, and @@ -8586,14 +8712,14 @@ in @code{org-agenda-custom-commands} take precedence. @noindent From the command line you may also use @example -emacs -f org-batch-store-agenda-views -kill +emacs -eval (org-batch-store-agenda-views) -kill @end example @noindent or, if you need to modify some parameters@footnote{Quoting depends on the system you use, please check the FAQ for examples.} @example emacs -eval '(org-batch-store-agenda-views \ - org-agenda-span month \ + org-agenda-span (quote month) \ org-agenda-start-day "2007-11-01" \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ @@ -8668,11 +8794,11 @@ the agenda). @node Markup, Exporting, Agenda Views, Top @chapter Markup for rich export -When exporting Org-mode documents, the exporter tries to reflect the +When exporting Org mode documents, the exporter tries to reflect the structure of the document as accurately as possible in the backend. Since export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting, -Org-mode has rules on how to prepare text for rich export. This section -summarizes the markup rules used in an Org-mode buffer. +Org mode has rules on how to prepare text for rich export. This section +summarizes the markup rules used in an Org mode buffer. @menu * Structural markup elements:: The basic structure as seen by the exporter @@ -8681,7 +8807,7 @@ summarizes the markup rules used in an Org-mode buffer. * Include files:: Include additional files into a document * Index entries:: Making an index * Macro replacement:: Use macros to create complex output -* Embedded LaTeX:: LaTeX can be freely used inside Org documents +* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents @end menu @node Structural markup elements, Images and tables, Markup, Markup @@ -8764,7 +8890,7 @@ the table of contents entirely, by configuring the variable @cindex text before first headline, markup rules @cindex #+TEXT -Org-mode normally exports the text before the first headline, and even uses +Org mode normally exports the text before the first headline, and even uses the first line as the document title. The text will be fully marked up. If you need to include literal HTML, @LaTeX{}, or DocBook code, use the special constructs described below in the sections for the individual exporters. @@ -8818,7 +8944,7 @@ can use this construct, which can also be used to format poetry. When quoting a passage from another document, it is customary to format this as a paragraph that is indented on both the left and the right margin. You -can include quotations in Org-mode documents like this: +can include quotations in Org mode documents like this: @cindex #+BEGIN_QUOTE @example @@ -8858,7 +8984,7 @@ multiple footnotes side by side. @cindex strike-through text, markup rules You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text -in the code and verbatim string is not processed for Org-mode specific +in the code and verbatim string is not processed for Org mode specific syntax; it is exported verbatim. @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements @@ -8892,8 +9018,8 @@ Toggle the COMMENT keyword at the beginning of an entry. @cindex tables, markup rules @cindex #+CAPTION @cindex #+LABEL -Both the native Org-mode tables (@pxref{Tables}) and tables formatted with -the @file{table.el} package will be exported properly. For Org-mode tables, +Both the native Org mode tables (@pxref{Tables}) and tables formatted with +the @file{table.el} package will be exported properly. For Org mode tables, the lines before the first horizontal separator line will become table header lines. You can use the following lines somewhere before the table to assign a caption and a label for cross references, and in the text you can refer to @@ -8963,16 +9089,16 @@ If the example is source code from a programming language, or any other text that can be marked up by font-lock in Emacs, you can ask for the example to look like the fontified Emacs buffer@footnote{This works automatically for the HTML backend (it requires version 1.34 of the @file{htmlize.el} package, -which is distributed with Org). Fontified code chunks in LaTeX can be +which is distributed with Org). Fontified code chunks in @LaTeX{} can be achieved using either the listings or the @url{http://code.google.com/p/minted, minted,} package. To use listings, turn on the variable @code{org-export-latex-listings} and ensure that the listings -package is included by the LaTeX header (e.g.@: by configuring +package is included by the @LaTeX{} header (e.g.@: by configuring @code{org-export-latex-packages-alist}). See the listings documentation for configuration options, including obtaining colored output. For minted it is necessary to install the program @url{http://pygments.org, pygments}, in addition to setting @code{org-export-latex-minted}, ensuring that the minted -package is included by the LaTeX header, and ensuring that the +package is included by the @LaTeX{} header, and ensuring that the @code{-shell-escape} option is passed to @file{pdflatex} (see @code{org-latex-to-pdf-process}). See the documentation of the variables @code{org-export-latex-listings} and @code{org-export-latex-minted} for @@ -8980,7 +9106,8 @@ further details.}. This is done with the @samp{src} block, where you also need to specify the name of the major mode that should be used to fontify the example@footnote{Code in @samp{src} blocks may also be evaluated either interactively or on export. See @pxref{Working With Source Code} for more -information on evaluating code blocks.}: +information on evaluating code blocks.}, see @ref{Easy Templates} for +shortcuts to easily insert code blocks. @cindex #+BEGIN_SRC @example @@ -9004,7 +9131,7 @@ cool. You can also add a @code{-r} switch which @i{removes} the labels from the source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the labels in the source code while using line numbers for the links, which might -be useful to explain those in an org-mode example code.}. With the @code{-n} +be useful to explain those in an Org mode example code.}. With the @code{-n} switch, links to these references will be labeled by the line numbers from the code listing, otherwise links will use the labels with no parentheses. Here is an example: @@ -9070,11 +9197,11 @@ include your @file{.emacs} file, you could use: The optional second and third parameter are the markup (e.g.@: @samp{quote}, @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the language for formatting the contents. The markup is optional; if it is not -given, the text will be assumed to be in Org-mode format and will be +given, the text will be assumed to be in Org mode format and will be processed normally. The include line will also allow additional keyword parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the first line and for each following line, @code{:minlevel} in order to get -org-mode content demoted to a specified level, as well as any options +Org mode content demoted to a specified level, as well as any options accepted by the selected markup. For example, to include a file as an item, use @@ -9117,7 +9244,7 @@ an index} for more information. -@node Macro replacement, Embedded LaTeX, Index entries, Markup +@node Macro replacement, Embedded @LaTeX{}, Index entries, Markup @section Macro replacement @cindex macro replacement, during export @cindex #+MACRO @@ -9142,7 +9269,7 @@ Macro expansion takes place during export, and some people use it to construct complex HTML code. -@node Embedded LaTeX, , Macro replacement, Markup +@node Embedded @LaTeX{}, , Macro replacement, Markup @section Embedded @LaTeX{} @cindex @TeX{} interpretation @cindex @LaTeX{} interpretation @@ -9152,7 +9279,7 @@ include scientific notes, which often require mathematical symbols and the occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on Donald E. Knuth's @TeX{} system. Many of the features described here as ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this -distinction.} is widely used to typeset scientific documents. Org-mode +distinction.} is widely used to typeset scientific documents. Org mode supports embedding @LaTeX{} code into its files, because many academics are used to writing and reading @LaTeX{} source code, and because it can be readily processed to produce pretty output for a number of export backends. @@ -9160,12 +9287,12 @@ readily processed to produce pretty output for a number of export backends. @menu * Special symbols:: Greek letters and other symbols * Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Previewing LaTeX fragments:: What will this snippet look like? +* @LaTeX{} fragments:: Complex formulas made easy +* Previewing @LaTeX{} fragments:: What will this snippet look like? * CDLaTeX mode:: Speed up entering of formulas @end menu -@node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX +@node Special symbols, Subscripts and superscripts, Embedded @LaTeX{}, Embedded @LaTeX{} @subsection Special symbols @cindex math symbols @cindex special symbols @@ -9178,7 +9305,7 @@ You can use @LaTeX{} macros to insert special symbols like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion for these macros is available, just type @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{} -code, Org-mode allows these macros to be present without surrounding math +code, Org mode allows these macros to be present without surrounding math delimiters, for example: @example @@ -9212,7 +9339,7 @@ buffer content which remains plain ASCII, but it overlays the UTF-8 character for display purposes only. @end table -@node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX +@node Subscripts and superscripts, @LaTeX{} fragments, Special symbols, Embedded @LaTeX{} @subsection Subscripts and superscripts @cindex subscript @cindex superscript @@ -9250,13 +9377,13 @@ In addition to showing entities as UTF-8 characters, this command will also format sub- and superscripts in a WYSIWYM way. @end table -@node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX +@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Subscripts and superscripts, Embedded @LaTeX{} @subsection @LaTeX{} fragments @cindex @LaTeX{} fragments @vindex org-format-latex-header Going beyond symbols and sub- and superscripts, a full formula language is -needed. Org-mode can contain @LaTeX{} math fragments, and it supports ways +needed. Org mode can contain @LaTeX{} math fragments, and it supports ways to process these for several export backends. When exporting to @LaTeX{}, the code is obviously left as it is. When exporting to HTML, Org invokes the @uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in @@ -9309,10 +9436,10 @@ can configure the option @code{org-format-latex-options} to deselect the ones you do not wish to have interpreted by the @LaTeX{} converter. @vindex org-export-with-LaTeX-fragments -LaTeX processing can be configured with the variable +@LaTeX{} processing can be configured with the variable @code{org-export-with-LaTeX-fragments}. The default setting is @code{t} which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and -LaTeX backends. You can also set this variable on a per-file basis using one +@LaTeX{} backends. You can also set this variable on a per-file basis using one of these lines: @example @@ -9322,9 +9449,9 @@ of these lines: #+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so} @end example -@node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX -@subsection Previewing LaTeX fragments -@cindex LaTeX fragments, preview +@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{} +@subsection Previewing @LaTeX{} fragments +@cindex @LaTeX{} fragments, preview If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to produce preview images of the typeset expressions: @@ -9349,18 +9476,18 @@ some aspects of the preview. In particular, the @code{:scale} (and for HTML export, @code{:html-scale}) property can be used to adjust the size of the preview images. -@node CDLaTeX mode, , Previewing LaTeX fragments, Embedded LaTeX -@subsection Using CDLa@TeX{} to enter math -@cindex CDLa@TeX{} +@node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{} +@subsection Using CD@LaTeX{} to enter math +@cindex CD@LaTeX{} -CDLa@TeX{} mode is a minor mode that is normally used in combination with a +CD@LaTeX{} mode is a minor mode that is normally used in combination with a major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of -environments and math templates. Inside Org-mode, you can make use of -some of the features of CDLa@TeX{} mode. You need to install +environments and math templates. Inside Org mode, you can make use of +some of the features of CD@LaTeX{} mode. You need to install @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. -Don't use CDLa@TeX{} mode itself under Org-mode, but use the light -version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it +Don't use CD@LaTeX{} mode itself under Org mode, but use the light +version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it on for the current buffer with @code{M-x org-cdlatex-mode}, or for all Org files with @@ -9369,7 +9496,7 @@ Org files with @end lisp When this mode is enabled, the following features are present (for more -details see the documentation of CDLa@TeX{} mode): +details see the documentation of CD@LaTeX{} mode): @itemize @bullet @kindex C-c @{ @item @@ -9377,7 +9504,7 @@ Environment templates can be inserted with @kbd{C-c @{}. @item @kindex @key{TAB} The @key{TAB} key will do template expansion if the cursor is inside a -@LaTeX{} fragment@footnote{Org-mode has a method to test if the cursor is +@LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is inside such a fragment, see the documentation of the function @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor @@ -9414,20 +9541,20 @@ is normal. @chapter Exporting @cindex exporting -Org-mode documents can be exported into a variety of other formats. For +Org mode documents can be exported into a variety of other formats. For printing and sharing of 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, while the XOXO format provides a solid base for exchange with a -broad range of other applications. @LaTeX{} export lets you use Org-mode and +broad range of other applications. @LaTeX{} export lets you use Org mode and its structured editing functions to easily create @LaTeX{} files. DocBook export makes it possible to convert Org files to many other formats using -DocBook tools. OpenDocumentText export allows seamless collaboration across -organizational boundaries. For project management you can create gantt and -resource charts by using TaskJuggler export. 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. +DocBook tools. OpenDocument Text(@acronym{ODT}) export allows seamless +colloboration across organizational boundaries. For project management you +can create gantt and resource charts by using TaskJuggler export. 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). @@ -9438,9 +9565,9 @@ enabled (default in Emacs 23). * The export dispatcher:: How to access exporter commands * 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 +* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook -* OpenDocumentText export:: Exporting to OpenDocumentText +* OpenDocument Text export:: Exporting to OpenDocument Text * TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO @@ -9456,7 +9583,8 @@ enabled (default in Emacs 23). @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}. +@code{org-export-select-tags} and @code{org-export-exclude-tags}, +respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}. @enumerate @item @@ -9517,10 +9645,11 @@ Insert template with export options, see example below. @vindex user-full-name @vindex user-mail-address @vindex org-export-default-language +@vindex org-export-date-timestamp-format @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, fixed, or a format string for @code{format-time-string} +#+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 @@ -9528,19 +9657,19 @@ Insert template with export options, see example below. #+TEXT: Some descriptive text to be inserted at the beginning. #+TEXT: Several lines may be given. #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... -#+BIND: lisp-var lisp-val, e.g.@:: org-export-latex-low-levels itemize +#+BIND: lisp-var lisp-val, e.g.@:: @code{org-export-latex-low-levels itemize} @r{You need to confirm using these, or configure @code{org-export-allow-BIND}} #+LINK_UP: the ``up'' link of an exported page #+LINK_HOME: the ``home'' link of an exported page -#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@} +#+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@} #+EXPORT_SELECT_TAGS: Tags that select a tree for export #+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export #+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file @end example @noindent -The OPTIONS line is a compact@footnote{If you want to configure many options -this way, you can use several OPTIONS lines.} form to specify export +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 @@ -9642,7 +9771,7 @@ not set, or force processing in the current Emacs process if set. @cindex Latin-1 export @cindex UTF-8 export -ASCII export produces a simple and very readable version of an Org-mode +ASCII export produces a simple and very readable version of an Org mode file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file with special characters and symbols available in these encodings. @@ -9697,18 +9826,18 @@ Links will be exported in a footnote-like style, with the descriptive part in the text and the link in a note before the next heading. See the variable @code{org-export-ascii-links-to-notes} for details and other options. -@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting +@node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting @section HTML export @cindex HTML export -Org-mode contains an 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. @menu * HTML Export commands:: How to invoke HTML export * HTML preamble and postamble:: How to insert a preamble and a postamble -* Quoting HTML tags:: Using direct HTML in Org-mode +* Quoting HTML tags:: Using direct HTML in Org mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output @@ -9746,11 +9875,11 @@ the region. This is good for cut-and-paste operations. @item C-c C-e v h/b/H/R Export only the visible part of the document. @item M-x org-export-region-as-html -Convert the region to HTML under the assumption that it was Org-mode +Convert the region to HTML under the assumption that it was Org mode syntax before. This is a global command that can be invoked in any buffer. @item M-x org-replace-region-by-HTML -Replace the active region (assumed to be in Org-mode syntax) by HTML +Replace the active region (assumed to be in Org mode syntax) by HTML code. @end table @@ -9852,7 +9981,7 @@ and @code{style} attributes for a link: @cindex #+ATTR_HTML @example -#+ATTR_HTML: title="The Org-mode homepage" style="color:red;" +#+ATTR_HTML: title="The Org mode homepage" style="color:red;" [[http://orgmode.org]] @end example @@ -9861,7 +9990,7 @@ and @code{style} attributes for a link: @cindex tables, in HTML @vindex org-export-html-table-tag -Org-mode tables are exported to HTML using the table tag defined in +Org mode tables are exported to HTML using the table tag defined in @code{org-export-html-table-tag}. The default setting makes tables without cell borders and frame. If you would like to change this for individual tables, place something like the following before the table: @@ -9870,7 +9999,7 @@ tables, place something like the following before the table: @cindex #+ATTR_HTML @example #+CAPTION: This is a table with lines around and between cells -#+ATTR_HTML: border="2" rules="all" frame="all" +#+ATTR_HTML: border="2" rules="all" frame="border" @end example @node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export @@ -9915,11 +10044,11 @@ You could use @code{http} addresses just as well. @cindex MathJax @cindex dvipng -@LaTeX{} math snippets (@pxref{LaTeX fragments}) can be displayed in two +@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two different ways on HTML pages. The default is to use the @uref{http://www.mathjax.org, MathJax system} which should work out of the box with Org mode installation because @code{http://orgmode.org} serves -@file{MathJax} for Org-mode users for small applications and for testing +@file{MathJax} for Org mode users for small applications and for testing purposes. @b{If you plan to use this regularly or on pages with significant page views, you should install@footnote{Installation instructions can be found on the MathJax website, see @@ -9985,7 +10114,7 @@ addition to any of the standard classes like for headlines, tables, etc. @example p.author @r{author information, including email} p.date @r{publishing date} -p.creator @r{creator info, about org-mode version} +p.creator @r{creator info, about org mode version} .title @r{document title} .todo @r{TODO keywords, all not-done states} .done @r{the DONE keywords, all states that count as done} @@ -10111,16 +10240,16 @@ You can choose default values for these options by customizing the variable @code{org-infojs-options}. If you always want to apply the script to your pages, configure the variable @code{org-export-html-use-infojs}. -@node LaTeX and PDF export, DocBook export, HTML export, Exporting +@node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting @section @LaTeX{} and PDF export @cindex @LaTeX{} export @cindex PDF export @cindex Guerry, Bastien -Org-mode contains a @LaTeX{} exporter written by Bastien Guerry. With -further processing@footnote{The default LaTeX output is designed for -processing with pdftex or latex. It includes packages that are not -compatible with xetex and possibly luatex. See the variables +Org mode contains a @LaTeX{} exporter written by Bastien Guerry. With +further processing@footnote{The default @LaTeX{} output is designed for +processing with @code{pdftex} or @LaTeX{}. It includes packages that are not +compatible with @code{xetex} and possibly @code{luatex}. See the variables @code{org-export-latex-default-packages-alist} and @code{org-export-latex-packages-alist}.}, this backend is also used to produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to @@ -10130,15 +10259,15 @@ structured in order to be correctly exported: respect the hierarchy of sections. @menu -* LaTeX/PDF export commands:: Which key invokes which commands +* @LaTeX{}/PDF export commands:: * Header and sectioning:: Setting up the export file structure -* Quoting LaTeX code:: Incorporating literal @LaTeX{} code -* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} -* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code +* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} +* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output * Beamer class export:: Turning the file into a presentation @end menu -@node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export +@node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export @subsection @LaTeX{} export commands @cindex region, active @@ -10160,11 +10289,11 @@ Export to a temporary buffer. Do not create a file. @item C-c C-e v l/L Export only the visible part of the document. @item M-x org-export-region-as-latex -Convert the region to @LaTeX{} under the assumption that it was Org-mode +Convert the region to @LaTeX{} under the assumption that it was Org mode syntax before. This is a global command that can be invoked in any buffer. @item M-x org-replace-region-by-latex -Replace the active region (assumed to be in Org-mode syntax) by @LaTeX{} +Replace the active region (assumed to be in Org mode syntax) by @LaTeX{} code. @orgcmd{C-c C-e p,org-export-as-pdf} Export as @LaTeX{} and then process to PDF. @@ -10190,13 +10319,13 @@ with a numeric prefix argument. For example, @noindent creates two levels of headings and does the rest as items. -@node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export +@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{}/PDF export commands, @LaTeX{} and PDF export @subsection Header and sectioning structure @cindex @LaTeX{} class @cindex @LaTeX{} sectioning structure @cindex @LaTeX{} header -@cindex header, for LaTeX files -@cindex sectioning structure, for LaTeX export +@cindex header, for @LaTeX{} files +@cindex sectioning structure, for @LaTeX{} export By default, the @LaTeX{} output uses the class @code{article}. @@ -10224,10 +10353,10 @@ can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the header. See the docstring of @code{org-export-latex-classes} for more information. -@node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export +@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export @subsection Quoting @LaTeX{} code -Embedded @LaTeX{} as described in @ref{Embedded LaTeX}, will be correctly +Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly inserted into the @LaTeX{} file. This includes simple macros like @samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore, you can add special code that should only be present in @LaTeX{} export with @@ -10236,7 +10365,7 @@ the following constructs: @cindex #+LaTeX @cindex #+BEGIN_LaTeX @example -#+LaTeX: Literal LaTeX code for export +#+LaTeX: Literal @LaTeX{} code for export @end example @noindent or @@ -10249,7 +10378,7 @@ All lines between these markers are exported literally @end example -@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export +@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export @subsection Tables in @LaTeX{} export @cindex tables, in @LaTeX{} export @@ -10286,7 +10415,7 @@ or to specify a multicolumn table with @code{tabulary} | ..... | ..... | @end example -@node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export +@node Images in @LaTeX{} export, Beamer class export, Tables in @LaTeX{} export, @LaTeX{} and PDF export @subsection Images in @LaTeX{} export @cindex images, inline in @LaTeX{} @cindex inlining images in @LaTeX{} @@ -10337,14 +10466,14 @@ will export the image wrapped in a @code{figure*} environment. If you need references to a label created in this way, write @samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}. -@node Beamer class export, , Images in LaTeX export, LaTeX and PDF export +@node Beamer class export, , Images in @LaTeX{} export, @LaTeX{} and PDF export @subsection Beamer class export -The LaTeX class @file{beamer} allows production of high quality presentations -using LaTeX and pdf processing. Org-mode has special support for turning an -Org-mode file or tree into a @file{beamer} presentation. +The @LaTeX{} class @file{beamer} allows production of high quality presentations +using @LaTeX{} and pdf processing. Org mode has special support for turning an +Org mode file or tree into a @file{beamer} presentation. -When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS: +When the @LaTeX{} class for the current buffer (as set with @code{#+LaTeX_CLASS: beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is @code{beamer}, a special export mode will turn the file or tree into a beamer presentation. Any tree with not-too-deep level nesting should in principle be @@ -10464,7 +10593,7 @@ Here is a simple example Org document that is intended for beamer export. For more information, see the documentation on Worg. -@node DocBook export, OpenDocumentText export, LaTeX and PDF export, Exporting +@node DocBook export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting @section DocBook export @cindex DocBook export @cindex PDF export @@ -10620,7 +10749,7 @@ set: @cindex #+LABEL @cindex #+ATTR_DOCBOOK @example -#+CAPTION: The logo of Org-mode +#+CAPTION: The logo of Org mode #+LABEL: unicorn-svg #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" [[./img/org-mode-unicorn.svg]] @@ -10663,39 +10792,46 @@ special characters included in XHTML entities: @c begin opendocument -@node OpenDocumentText export, TaskJuggler export, DocBook export, Exporting -@section OpenDocumentText export -@cindex OpenDocumentText export +@node OpenDocument Text export, TaskJuggler export, DocBook export, Exporting +@section OpenDocument Text export @cindex K, Jambunathan - -Org-mode 7.6 supports export to OpenDocumentText format using -@file{org-odt.el} module contributed by Jambunathan K. This module can be -enabled in one of the following ways based on your mode of installation. - -@enumerate -@item -If you have downloaded the Org from the Web, either as a distribution -@file{.zip} or @file{.tar} file, or as a Git archive, enable the @code{odt} -option in variable @code{org-modules}. -@item -If you are using Org that comes bundled with Emacs, then you can install the -OpenDocumentText exporter using the package manager. To do this, customize -the variable @code{package-archives} to include -@uref{http://orgmode.org/pkg/releases/} as one of the package archives. -@end enumerate +@cindex ODT +@cindex OpenDocument +@cindex export, OpenDocument +@cindex LibreOffice +@cindex org-odt.el +@cindex org-modules + +Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text +(@acronym{ODT}) format using the @file{org-odt.el} module. Documents created +by this exporter use the @cite{OpenDocument-v1.2 +specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, +Open Document Format for Office Applications (OpenDocument) Version 1.2}} and +are compatible with LibreOffice 3.4. @menu -* OpenDocumentText export commands::How to invoke OpenDocumentText export -* Applying Custom Styles:: How to apply custom styles to the output -* Converting to Other formats:: How to convert to formats like doc, docx etc -* Links in OpenDocumentText export:: How links will be interpreted and formatted -* Tables in OpenDocumentText export:: Tables are exported as HTML tables -* Images in OpenDocumentText export:: How to insert figures into DocBook output -* Additional Documentation:: Where to find more information +* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on +* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export +* Applying custom styles:: How to apply custom styles to the output +* Links in @acronym{ODT} export:: How links will be interpreted and formatted +* Tables in @acronym{ODT} export:: How Tables are exported +* Images in @acronym{ODT} export:: How to insert images +* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted +* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted +* Advanced topics in @acronym{ODT} export:: Read this if you are a power user @end menu -@node OpenDocumentText export commands, Applying Custom Styles, OpenDocumentText export, OpenDocumentText export -@subsection OpenDocumentText export commands +@node Pre-requisites for @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export, OpenDocument Text export +@subsection Pre-requisites for @acronym{ODT} export +@cindex zip +The @acronym{ODT} exporter relies on the @file{zip} program to create the final +output. Check the availability of this program before proceeding further. + +@node @acronym{ODT} export commands, Applying custom styles, Pre-requisites for @acronym{ODT} export, OpenDocument Text export +@subsection @acronym{ODT} export commands + +@subsubheading Exporting to @acronym{ODT} +@anchor{x-export-to-odt} @cindex region, active @cindex active region @@ -10703,113 +10839,791 @@ the variable @code{package-archives} to include @table @kbd @orgcmd{C-c C-e o,org-export-as-odt} @cindex property EXPORT_FILE_NAME -Export as OpenDocumentText file. For an Org file, @file{myfile.org}, the -OpenDocumentText file will be @file{myfile.odt}. The file will be -overwritten without warning. If there is an active region@footnote{This -requires @code{transient-mark-mode} to be turned on}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. + +Export as OpenDocument Text file. +@vindex org-export-odt-preferred-output-format +If @code{org-export-odt-preferred-output-format} is specified, automatically +convert the exported file to that format. +@xref{x-export-to-other-formats,,Automatically exporting to other formats}. + +For an Org file @file{myfile.org}, the @acronym{ODT} file will be +@file{myfile.odt}. The file will be overwritten without warning. If there +is an active region,@footnote{This requires @code{transient-mark-mode} to be +turned on} only the region will be exported. If the selected region is a +single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the +tree head will become the document title. If the tree head entry has, or +inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the +export. + @orgcmd{C-c C-e O,org-export-as-odt-and-open} -Export as OpenDocumentText file and open the resulting file. +Export as OpenDocument Text file and open the resulting file. +@vindex org-export-odt-preferred-output-format +If @code{org-export-odt-preferred-output-format} is specified, open the +converted file instead. +@xref{x-export-to-other-formats,,Automatically exporting to other formats}. @end table -@node Applying Custom Styles, Converting to Other formats, OpenDocumentText export commands, OpenDocumentText export -@subsection Applying Custom Styles +@subsubheading Automatically exporting to other formats +@anchor{x-export-to-other-formats} +@vindex org-export-odt-preferred-output-format +Very often, you will find yourself exporting to @acronym{ODT} format, only to +immediately save the exported document to a different format like @samp{pdf}. +In such cases, you will find it convenient to configure a converter +(@pxref{Exporting and converting to other formats}) and specify your +preferred output format by customizing the variable +@code{org-export-odt-preferred-output-format}. This way, the export commands +(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to also export to +the preferred format. + +@node Applying custom styles, Links in @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export +@subsection Applying custom styles @cindex styles, custom @cindex template, custom -@vindex org-export-odt-styles-file +The @acronym{ODT} exporter ships with a set of OpenDocument styles +(@pxref{Working with OpenDocument style files}) that ensure a well-formatted +output. These factory styles, however, may not cater to your specific +tastes. To customize the output, you can either modify the above styles +files directly, or generate the required styles using an application like +LibreOffice. The latter method is suitable for expert and non-expert +users alike, and is described here. -OpenDocumentExporter ships with a custom @file{styles.xml} for formatting of -the exported file. To customize the output to suit your needs you can use -one of the following methods: +@subsubsection Applying custom styles - the easy way @enumerate @item -Customize the variable @code{org-export-odt-styles-file} to point to either a -@file{styles.xml} file, a OpenDocument Text Template file @code{.ott} or a -combination of Text or Template Document together with a set of member files. -Use the first two options if the styles.xml has no references to additional -set of files and use the last option if the @file{styles.xml} references -additional files like header and footer images. +Create a sample @file{example.org} file with the below settings and export it +to @acronym{ODT} format. + +@example +#+OPTIONS: H:10 num:t +@end example + +@item +Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist} +to locate the target styles - these typically have the @samp{Org} prefix - +and modify those to your taste. Save the modified file either as an +OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file. + @item -Use an external tool like unoconv to apply custom templates. +@cindex #+ODT_STYLES_FILE +@vindex org-export-odt-styles-file +Customize the variable @code{org-export-odt-styles-file} and point it to the +newly created file. For additional configuration options +@pxref{x-overriding-factory-styles,,Overriding factory styles}. + +If you would like to choose a style on a per-file basis, you can use the +@code{#+ODT_STYLES_FILE} option. A typical setting will look like + +@example +#+ODT_STYLES_FILE: "/path/to/example.ott" +@end example + +or + +@example +#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")) +@end example + @end enumerate -For best results, it is necessary that the style names used by -OpenDocumentText exporter match that used in the @file{styles.xml}. +@subsubsection Using third-party styles and templates + +You can use third-party styles and templates for customizing your output. +This will produce the desired output only if the template provides all +style names that the @samp{ODT} exporter relies on. Unless this condition is +met, the output is going to be less than satisfactory. So it is highly +recommended that you only work with templates that are directly derived from +the factory settings. + +@node Links in @acronym{ODT} export, Tables in @acronym{ODT} export, Applying custom styles, OpenDocument Text export +@subsection Links in @acronym{ODT} export +@cindex tables, in DocBook export + +The @acronym{ODT} exporter creates cross-references (aka bookmarks) for +internal links. It creates Internet-style links for all other links. + +@node Tables in @acronym{ODT} export, Images in @acronym{ODT} export, Links in @acronym{ODT} export, OpenDocument Text export +@subsection Tables in @acronym{ODT} export +@cindex tables, in DocBook export -@node Converting to Other formats, Links in OpenDocumentText export, Applying Custom Styles, OpenDocumentText export -@subsection Converting to Other formats +Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el} +tables is supported. However, export of complex @file{table.el} tables - +tables that have column or row spans - is not supported. Such tables are +stripped from the exported document. +By default, a table is exported with top and bottom frames and with +rules separating row and column groups (@pxref{Column groups}). If the table +specifies alignment and relative width for its columns (@pxref{Column width +and alignment}) then these are honored on export.@footnote{The column widths +are interpreted as weighted ratios with the default weight being 1} + +@cindex #+ATTR_ODT +If you are not satisfied with the default formatting of tables, you can +create custom table styles and associate them with a table using +the @code{#+ATTR_ODT} line. @xref{Customizing tables in @acronym{ODT} export}. + +@node Images in @acronym{ODT} export, Math formatting in @acronym{ODT} export, Tables in @acronym{ODT} export, OpenDocument Text export +@subsection Images in @acronym{ODT} export +@cindex images, embedding in @acronym{ODT} +@cindex embedding images in @acronym{ODT} + +@subsubheading Embedding images +You can embed images within the exported document by providing a link to the +desired image file with no link description. For example, to embed +@samp{img.png} do either of the following: + +@example +[[file:img.png]] +@end example + +@example +[[./img.png]] +@end example + +@subsubheading Embedding clickable images +You can create clickable images by providing a link whose description is a +link to an image file. For example, to embed a image +@file{org-mode-unicorn.png} which when clicked jumps to +@uref{http://Orgmode.org} website, do the following + +@example +[[http://orgmode.org][./org-mode-unicorn.png]] +@end example + +@subsubheading Sizing and scaling of embedded images + +You can control the size and scale of the embedded images using the +@code{#+ATTR_ODT} attribute. + +@vindex org-export-odt-pixels-per-inch +Note that the exporter specifies the desired size of the image in the final +document in units of centimetres. In order to scale the embedded images, the +exporter needs to compute the size of the image. This is done by retrieving +the image size in pixels and converting the pixel units to centimetres using +@code{org-export-odt-pixels-per-inch}. The default value of this variable is +set to @code{display-pixels-per-inch}. You can tweak this variable to +achieve the best results. + +The examples below illustrate the various possibilities. + +@table @asis + +@item Explicitly size the image +To embed @file{img.png} as a 10 cm x 10 cm image, do the following: + +@example +#+ATTR_ODT: :width 10 :height 10 +[[./img.png]] +@end example + +@item Scale the image +To embed @file{img.png} at half its size, do the following: + +@example +#+ATTR_ODT: :scale 0.5 +[[./img.png]] +@end example + +@item Scale the image to a specific width +To embed @file{img.png} with a width of 10 cm while retaining the original +height:width ratio, do the following: + +@example +#+ATTR_ODT: :width 10 +[[./img.png]] +@end example + +@item Scale the image to a specific height +To embed @file{img.png} with a height of 10 cm while retaining the original +height:width ratio, do the following + +@example +#+ATTR_ODT: :height 10 +[[./img.png]] +@end example +@end table + +@node Math formatting in @acronym{ODT} export, Literal examples in @acronym{ODT} export, Images in @acronym{ODT} export, OpenDocument Text export +@subsection Math formatting in @acronym{ODT} export + +The @acronym{ODT} exporter has special support for handling math. + +@menu +* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments +* Working with MathML or OpenDocument formula files:: How to embed equations in native format +@end menu + +@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 +@subsubsection Working with @LaTeX{} math snippets + +@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT +document in one of the following ways: + +@cindex MathML +@enumerate +@item MathML + +This option is activated on a per-file basis with + +@example +#+OPTIONS: LaTeX:t +@end example + +With this option, @LaTeX{} fragments are first converted into MathML +fragments using an external @LaTeX{}-to-MathML converter program. The +resulting MathML fragments are then embedded as an OpenDocument Formula in +the exported document. + +@vindex org-latex-to-mathml-convert-command +@vindex org-latex-to-mathml-jar-file + +You can specify the @LaTeX{}-to-MathML converter by customizing the variables +@code{org-latex-to-mathml-convert-command} and +@code{org-latex-to-mathml-jar-file}. + +If you prefer to use @file{MathToWeb}@footnote{See +@uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your +converter, you can configure the above variables as shown below. + +@lisp +(setq org-latex-to-mathml-convert-command + "java -jar %j -unicode -force -df %o %I" + org-latex-to-mathml-jar-file + "/path/to/mathtoweb.jar") +@end lisp + +You can use the following commands to quickly verify the reliability of +the @LaTeX{}-to-MathML converter. + +@table @kbd + +@item M-x org-export-as-odf +Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file. + +@item M-x org-export-as-odf-and-open +Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file and +open the formula file with the system-registered application. +@end table + +@cindex dvipng +@item PNG images + +This option is activated on a per-file basis with + +@example +#+OPTIONS: LaTeX:dvipng +@end example + +With this option, @LaTeX{} fragments are processed into PNG images and the +resulting images are embedded in the exported document. This method requires +that the @file{dvipng} program be available on your system. +@end enumerate + +@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in @acronym{ODT} export +@subsubsection Working with MathML or OpenDocument formula files + +For various reasons, you may find embedding @LaTeX{} math snippets in an +@acronym{ODT} document less than reliable. In that case, you can embed a +math equation by linking to its MathML(@file{.mml}) source or its +OpenDocument formula (@file{.odf}) file as shown below: + +@example +[[./equation.mml]] +@end example + +or + +@example +[[./equation.odf]] +@end example + +@node Literal examples in @acronym{ODT} export, Advanced topics in @acronym{ODT} export, Math formatting in @acronym{ODT} export, OpenDocument Text export +@subsection Literal examples in @acronym{ODT} export + +Export of literal examples (@pxref{Literal examples}) with full fontification +is supported. This feature is enabled by default and is activated +automatically if an enhanced version of @file{htmlfontify.el} is available in +the @code{load-path}.@footnote{The @file{htmlfontify.el} that ships with +standard Emacs <= 24.1 has no support for @acronym{ODT} fontification. A +copy of the proposed version is available as an attachment to +@url{http://debbugs.gnu.org/cgi/bugreport.cgi?msg=5;filename=htmlfontify.el;att=9;bug=9914, +Emacs Bug #9914}.} + +@vindex org-export-odt-fontify-srcblocks + +The character styles used for fontification of the literal blocks are +auto-generated by the exporter in conjunction with @file{htmlfontify.el} +library and need not be included in the default @file{styles.xml} file. +These auto-generated styles have the @samp{OrgSrc} prefix and inherit their color +based on the face used by Emacs @code{font-lock} library. + +@vindex org-export-odt-create-custom-styles-for-srcblocks +If you prefer to use your own custom styles for fontification and disable +their auto-generation altogether, you can do so by customizing the variable +@code{org-export-odt-create-custom-styles-for-srcblocks}. + +You can turn off fontification support for literal examples by customizing +the variable @code{org-export-odt-fontify-srcblocks}. + + +@node Advanced topics in @acronym{ODT} export, , Literal examples in @acronym{ODT} export, OpenDocument Text export +@subsection Advanced topics in @acronym{ODT} export + +If you rely heavily on @acronym{ODT} export, you may want to exploit the full +set of features that the exporter offers. This section describes features +that would be of interest to power users. + +@menu +* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats +* Working with OpenDocument style files:: Explore the internals +* Creating one-off styles:: How to produce custom highlighting etc +* Customizing tables in @acronym{ODT} export:: How to define and use Table templates +* Validating OpenDocument XML:: How to debug corrupt OpenDocument files +@end menu + +@node Exporting and converting to other formats, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export, Advanced topics in @acronym{ODT} export +@subsubsection Exporting and converting to other formats @cindex convert @cindex doc, docx -@vindex org-export-odt-styles-file - -Often times there is a need to convert OpenDocumentText files to other -formats like doc, docx or pdf. You can accomplish this by one of the -following methods: +The @acronym{ODT} exporter adds support for exporting Org outlines to formats +that are not supported natively by Org. It also adds support to convert +document from one format to another. To use these features, you need to +configure a command-line converter. Once a command-line converter is +configured you can use it to extend the list of formats to which Org can +export. @xref{x-export-to-other-formats,,Automatically exporting to other +formats}. You can also use it to perform one-off document conversion as +detailed below. +@vindex org-export-odt-convert @table @kbd -@item M-x org-lparse -Export the outline first to one of the native formats (like OpenDocumentText) -and immediately post-process it to other formats using an external converter. -@item M-x org-lparse-convert -Export an existing document to other formats using an external converter. +@item M-x org-export-odt-convert +Convert an existing document from one format to another as determined by the +variable @code{org-export-odt-convert-capabilities} +(@pxref{x-odt-converter-capabilities,,Configure converter +capabilities}). @strong{Please note} that you can use this command to even +convert documents that are produced outside of Org and in other formats than +@acronym{ODT} format. @end table -You can choose the converter used for conversion by customizing the variable -@code{org-lparse-convert-process}. +@subsubheading Pre-configured converters -@node Links in OpenDocumentText export, Tables in OpenDocumentText export, Converting to Other formats, OpenDocumentText export -@subsection Links in OpenDocumentText export -@cindex tables, in DocBook export +@cindex converter +The @acronym{ODT} exporter supports two converters out of the box: -OpenDocumentExporter creates cross-references (aka bookmarks) for links that -are destined locally. It creates internet style links for all other links. +@enumerate -@node Tables in OpenDocumentText export, Images in OpenDocumentText export, Links in OpenDocumentText export, OpenDocumentText export -@subsection Tables in OpenDocumentText export -@cindex tables, in DocBook export +@cindex @file{unoconv} +@item @file{unoconv} -Export of @file{table.el} tables with row or column spanning is not -supported. Such tables are stripped from the exported document. +This converter is available as an installable package in your favorite +distribution. -@node Images in OpenDocumentText export, Additional Documentation, Tables in OpenDocumentText export, OpenDocumentText export -@subsection Images in OpenDocumentText export -@cindex images, embedding in OpenDocumentText -@cindex embedding images in OpenDocumentText +@cindex @file{BasicODConverter} +@item @file{BasicODConverter} -OpenDocumentText exporter can embed images within the exported document. To -embed images, provide a link to the desired image file with no link -description. For example, the following links @samp{[[file:img.jpg]]} or -@samp{[[./img.jpg]]}, will result in embedding of @samp{img.jpg} in the -exported file. +@vindex org-odt-data-dir +This converter is distributed as a LibreOffice extension and can be found in +your Org distribution. See the subdirectory pointed to by the variable +@code{org-odt-data-dir}. -The exporter can also embed scaled and explicitly sized images within the -exported document. The markup of the scale and size specifications has not -been standardized yet and is hence conveniently skipped in this document. +@end enumerate + +@subsubheading Installing a new converter +If you prefer to use a converter other than the two mentioned above, then you +may have to do additional configuration. You can proceed as follows: + +@enumerate +@item Register the converter + +@vindex org-export-odt-convert-processes +Name your converter and add it to the list of known converters by customizing +the variable @code{org-export-odt-convert-processes}. Also specify how the +converter can be invoked via command-line to effect the conversion. + +@item Configure its capabilities +@vindex org-export-odt-convert-capabilities -The exporter can also make an image the clickable part of a link. To create -clickable images, provide a link whose description is a link to an image -file. For example, the following link -@samp{[[http://orgmode.org][./img.jpg]]}, will result in a clickable image -that links to @uref{http://Orgmode.org} website. +@anchor{x-odt-converter-capabilities} -@node Additional Documentation, , Images in OpenDocumentText export, OpenDocumentText export -@subsection Additional documentation +Specify the set of formats the converter can handle by customizing the +variable @code{org-export-odt-convert-capabilities}. Use the default value +for this variable as a guide for configuring your converter. As suggested by +the default setting, you can specify the full set of formats supported by the +converter and not limit yourself to specifying formats that are related to +just the OpenDocument Text format. + +@item Choose the converter + +@vindex org-export-odt-convert-process +Select the newly added converter as the preferred one by customizing the +variable @code{org-export-odt-convert-process}. +@end enumerate + +@node Working with OpenDocument style files, Creating one-off styles, Exporting and converting to other formats, Advanced topics in @acronym{ODT} export +@subsubsection Working with OpenDocument style files +@cindex styles, custom +@cindex template, custom -The OpenDocumentText exporter is still in development. For up to date -information, please follow Org mailing list @email{emacs-orgmode@@gnu.org} -closely. +This section explores the internals of the @acronym{ODT} exporter and the +means by which it produces styled documents. Read this section if you are +interested in exploring the automatic and custom OpenDocument styles used by +the exporter. + +@anchor{x-factory-styles} +@subsubheading Factory styles + +The @acronym{ODT} exporter relies on two files for generating its output. +These files are bundled with the distribution under the directory pointed to +by the variable @code{org-odt-styles-dir}. The two files are: + +@itemize +@anchor{x-orgodtstyles-xml} +@item +@file{OrgOdtStyles.xml} + +This file contributes to the @file{styles.xml} file of the final @samp{ODT} +document. This file gets modified for the following purposes: +@enumerate + +@item +To control outline numbering based on user settings. + +@item +To add styles generated by @file{htmlfontify.el} for fontification of code +blocks. +@end enumerate + +@anchor{x-orgodtcontenttemplate-xml} +@item +@file{OrgOdtContentTemplate.xml} + +This file contributes to the @file{content.xml} file of the final @samp{ODT} +document. The contents of the Org outline are inserted between the +@samp{<office:text>}@dots{}@samp{</office:text>} elements of this file. + +Apart from serving as a template file for the final @file{content.xml}, the +file serves the following purposes: +@enumerate + +@item +It contains automatic styles for formatting of tables which are referenced by +the exporter. + +@item +It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>} +elements that control how various entities - tables, images, equations etc - +are numbered. +@end enumerate +@end itemize + +@anchor{x-overriding-factory-styles} +@subsubheading Overriding factory styles +The following two variables control the location from which the @acronym{ODT} +exporter picks up the custom styles and content template files. You can +customize these variables to override the factory styles used by the +exporter. + +@itemize +@anchor{x-org-export-odt-styles-file} +@item +@code{org-export-odt-styles-file} + +Use this variable to specify the @file{styles.xml} that will be used in the +final output. You can specify one of the following values: + +@enumerate +@item A @file{styles.xml} file + +Use this file instead of the default @file{styles.xml} + +@item A @file{.odt} or @file{.ott} file + +Use the @file{styles.xml} contained in the specified OpenDocument Text or +Template file + +@item A @file{.odt} or @file{.ott} file and a subset of files contained within them + +Use the @file{styles.xml} contained in the specified OpenDocument Text or +Template file. Additionally extract the specified member files and embed +those within the final @samp{ODT} document. + +Use this option if the @file{styles.xml} file references additional files +like header and footer images. + +@item @code{nil} + +Use the default @file{styles.xml} +@end enumerate + +@anchor{x-org-export-odt-content-template-file} +@item +@code{org-export-odt-content-template-file} + +Use this variable to specify the blank @file{content.xml} that will be used +in the final output. +@end itemize + +@node Creating one-off styles, Customizing tables in @acronym{ODT} export, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export +@subsubsection Creating one-off styles + +There are times when you would want one-off formatting in the exported +document. You can achieve this by embedding raw OpenDocument XML in the Org +file. The use of this feature is better illustrated with couple of examples. + +@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: + +@example +@@<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 +@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a +custom @samp{Highlight} style as shown below. + +@example +<style:style style:name="Highlight" style:family="text"> + <style:text-properties fo:background-color="#ff0000"/> +</style:style> +@end example + +@item Embedding a one-line OpenDocument XML + +You can add a simple OpenDocument one-liner using the @code{#+ODT:} +directive. For example, to force a page break do the following: + +@example +#+ODT: <text:p text:style-name="PageBreak"/> +@end example + +@strong{Hint:} To see the above example in action, edit your +@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a +custom @samp{PageBreak} style as shown below. + +@example +<style:style style:name="PageBreak" style:family="paragraph" + style:parent-style-name="Text_20_body"> + <style:paragraph-properties fo:break-before="page"/> +</style:style> +@end example + +@item Embedding a block of OpenDocument XML + +You can add a large block of OpenDocument XML using the +@code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct. + +For example, to create a one-off paragraph that uses bold text, do the +following: + +@example +#+BEGIN_ODT +<text:p text:style-name="Text_20_body_20_bold"> +This paragraph is specially formatted and uses bold text. +</text:p> +#+END_ODT +@end example + +@end enumerate + +@node Customizing tables in @acronym{ODT} export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in @acronym{ODT} export +@subsubsection Customizing tables in @acronym{ODT} export +@cindex tables, in ODT export + +@cindex #+ATTR_ODT +You can override the default formatting of the table by specifying a custom +table style with the @code{#+ATTR_ODT} line. For a discussion on default +formatting of tables @pxref{Tables in @acronym{ODT} export}. + +This feature closely mimics the way table templates are defined in the +OpenDocument-v1.2 +specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, +OpenDocument-v1.2 Specification}} + + + +@subsubheading Custom table styles - an illustration + +To have a quick preview of this feature, install the below setting and export +the table that follows. + +@lisp +(setq org-export-odt-table-styles + (append org-export-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) +@end lisp + +@example +#+ATTR_ODT: TableWithHeaderRowAndColumn +| Name | Phone | Age | +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end example + +In the above example, you used a template named @samp{Custom} and installed +two table styles with the names @samp{TableWithHeaderRowAndColumn} and +@samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument +styles needed for producing the above template have been pre-defined for you. +These styles are available under the section marked @samp{Custom Table +Template} in @file{OrgOdtContentTemplate.xml} +(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need +additional templates you have to define these styles yourselves. + +@subsubheading Custom table styles - the nitty-gritty +To use this feature proceed as follows: + +@enumerate +@item +Create a table template@footnote{See the @code{<table:table-template>} +element of the OpenDocument-v1.2 specification} + +A table template is nothing but a set of @samp{table-cell} and +@samp{paragraph} styles for each of the following table cell categories: + +@itemize @minus +@item Body +@item First column +@item Last column +@item First row +@item Last row +@item Even row +@item Odd row +@item Even column +@item Odd Column +@end itemize + +The names for the above styles must be chosen based on the name of the table +template using a well-defined convention. + +The naming convention is better illustrated with an example. For a table +template with the name @samp{Custom}, the needed style names are listed in +the following table. + +@multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph} +@headitem Table cell type +@tab @code{table-cell} style +@tab @code{paragraph} style +@item +@tab +@tab +@item Body +@tab @samp{CustomTableCell} +@tab @samp{CustomTableParagraph} +@item First column +@tab @samp{CustomFirstColumnTableCell} +@tab @samp{CustomFirstColumnTableParagraph} +@item Last column +@tab @samp{CustomLastColumnTableCell} +@tab @samp{CustomLastColumnTableParagraph} +@item First row +@tab @samp{CustomFirstRowTableCell} +@tab @samp{CustomFirstRowTableParagraph} +@item Last row +@tab @samp{CustomLastRowTableCell} +@tab @samp{CustomLastRowTableParagraph} +@item Even row +@tab @samp{CustomEvenRowTableCell} +@tab @samp{CustomEvenRowTableParagraph} +@item Odd row +@tab @samp{CustomOddRowTableCell} +@tab @samp{CustomOddRowTableParagraph} +@item Even column +@tab @samp{CustomEvenColumnTableCell} +@tab @samp{CustomEvenColumnTableParagraph} +@item Odd column +@tab @samp{CustomOddColumnTableCell} +@tab @samp{CustomOddColumnTableParagraph} +@end multitable + +To create a table template with the name @samp{Custom}, define the above +styles in the +@code{<office:automatic-styles>}...@code{</office:automatic-styles>} element +of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory +styles}). + +@item +Define a table style@footnote{See the attributes @code{table:template-name}, +@code{table:use-first-row-styles}, @code{table:use-last-row-styles}, +@code{table:use-first-column-styles}, @code{table:use-last-column-styles}, +@code{table:use-banding-rows-styles}, and +@code{table:use-banding-column-styles} of the @code{<table:table>} element in +the OpenDocument-v1.2 specification} + +@vindex org-export-odt-table-styles +To define a table style, create an entry for the style in the variable +@code{org-export-odt-table-styles} and specify the following: + +@itemize @minus +@item the name of the table template created in step (1) +@item the set of cell styles in that template that are to be activated +@end itemize + +For example, the entry below defines two different table styles +@samp{TableWithHeaderRowsAndColumns} and @samp{TableWithHeaderColumns} based +on the same template @samp{Custom}. The styles achieve their intended effect +by selectively activating the individual cell styles in that template. + +@lisp +(setq org-export-odt-table-styles + (append org-export-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) +@end lisp + +@item +Associate a table with the table style + +To do this, specify the table style created in step (2) as part of +the @code{ATTR_ODT} line as shown below. + +@example +#+ATTR_ODT: TableWithHeaderRowAndColumn +| Name | Phone | Age | +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end example +@end enumerate + +@node Validating OpenDocument XML, , Customizing tables in @acronym{ODT} export, Advanced topics in @acronym{ODT} export +@subsubsection Validating OpenDocument XML + +Occasionally, you will discover that the document created by the +@acronym{ODT} exporter cannot be opened by your favorite application. One of +the common reasons for this is that the @file{.odt} file is corrupt. In such +cases, you may want to validate the document against the OpenDocument RELAX +NG Compact Syntax (RNC) schema. + +For de-compressing the @file{.odt} file@footnote{@file{.odt} files are +nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For +general help with validation (and schema-sensitive editing) of XML files: +@inforef{Introduction,,nxml-mode}. + +@vindex org-export-odt-schema-dir +If you have ready access to OpenDocument @file{.rnc} files and the needed +schema-locating rules in a single folder, you can customize the variable +@code{org-export-odt-schema-dir} to point to that directory. The +@acronym{ODT} exporter will take care of updating the +@code{rng-schema-locating-files} for you. @c end opendocument -@node TaskJuggler export, Freemind export, OpenDocumentText export, Exporting +@node TaskJuggler export, Freemind export, OpenDocument Text export, Exporting @section TaskJuggler export @cindex TaskJuggler export @cindex Project management @@ -10820,7 +11634,7 @@ resource assignments based on the project outline and the constraints that you have provided. The TaskJuggler exporter is a bit different from other exporters, such as the -HTML and LaTeX exporters for example, in that it does not export all the +@code{HTML} and @LaTeX{} exporters for example, in that it does not export all the nodes of a document or strictly follow the order of the nodes in the document. @@ -10842,7 +11656,7 @@ Export as TaskJuggler file and then open the file with TaskJugglerUI. @subsection Tasks @vindex org-export-taskjuggler-project-tag -Create your tasks as you usually do with Org-mode. Assign efforts to each +Create your tasks as you usually do with Org mode. Assign efforts to each task using properties (it is easiest to do this in the column view). You should end up with something similar to the example by Peter Jones in @url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}. @@ -10954,9 +11768,9 @@ file will be @file{myfile.mm}. @section XOXO export @cindex XOXO export -Org-mode contains an exporter that produces XOXO-style output. +Org mode contains an exporter that produces XOXO-style output. Currently, this exporter only handles the general outline structure and -does not interpret any additional Org-mode features. +does not interpret any additional Org mode features. @table @kbd @orgcmd{C-c C-e x,org-export-as-xoxo} @@ -10975,10 +11789,10 @@ Export only the visible part of the document. @vindex org-icalendar-use-scheduled @vindex org-icalendar-categories @vindex org-icalendar-alarm-time -Some people use Org-mode for keeping track of projects, but still prefer a +Some people use Org mode for keeping track of projects, but still prefer a standard calendar application for anniversaries and appointments. In this case it can be useful to show deadlines and other time-stamped items in Org -files in the calendar application. Org-mode can export calendar information +files in the calendar application. Org mode can export calendar information in the standard iCalendar format. If you also want to have TODO entries included in the export, configure the variable @code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT, @@ -11422,7 +12236,7 @@ Defaults to @code{nil}. @subsection Generating an index @cindex index, in a publishing project -Org-mode can generate an index across the files of a publishing project. +Org mode can generate an index across the files of a publishing project. @multitable @columnfractions 0.25 0.75 @item @code{:makeindex} @@ -11442,7 +12256,7 @@ a title, style information, etc. For those people already utilizing third party sync tools such as @command{rsync} or @command{unison}, it might be preferable not to use the built in -@i{remote} publishing facilities of Org-mode which rely heavily on +@i{remote} publishing facilities of Org mode which rely heavily on Tramp. Tramp, while very useful and powerful, tends not to be so efficient for multiple file transfer and has been known to cause problems under heavy usage. @@ -11581,7 +12395,7 @@ This may be necessary in particular if files include other files via @cindex Davison, Dan @cindex source code, working with -Source code can be included in Org-mode documents using a @samp{src} block, +Source code can be included in Org mode documents using a @samp{src} block, e.g.@: @example @@ -11592,26 +12406,26 @@ e.g.@: #+END_SRC @end example -Org-mode provides a number of features for working with live source code, +Org mode provides a number of features for working with live source code, including editing of code blocks in their native major-mode, evaluation of code blocks, converting code blocks into source files (known as @dfn{tangling} in literate programming), and exporting code blocks and their results in several formats. This functionality was contributed by Eric Schulte and Dan Davison, and was originally named Org-babel. -The following sections describe Org-mode's code block handling facilities. +The following sections describe Org mode's code block handling facilities. @menu * Structure of code blocks:: Code block syntax described * Editing source code:: Language major-mode editing * Exporting code blocks:: Export contents and/or results * Extracting source code:: Create pure source code files -* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Evaluating code blocks:: Place results of evaluation in the Org mode buffer * Library of Babel:: Use and contribute to a library of useful code blocks * Languages:: List of supported code block languages * Header arguments:: Configure code block functionality * Results of evaluation:: How evaluation results are handled -* Noweb reference syntax:: Literate programming in Org-mode +* Noweb reference syntax:: Literate programming in Org mode * Key bindings and useful functions:: Work quickly with code blocks * Batch execution:: Call functions from the command line @end menu @@ -11623,18 +12437,26 @@ The following sections describe Org-mode's code block handling facilities. @section Structure of code blocks @cindex code block, structure @cindex source code, block structure +@cindex #+NAME +@cindex #+BEGIN_SRC -The structure of code blocks is as follows: +Live code blocks can be specified with a @samp{src} block or +inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's +@ref{Easy Templates} system} The structure of a @samp{src} block is @example -#+srcname: <name> -#+begin_src <language> <switches> <header arguments> +#+NAME: <name> +#+BEGIN_SRC <language> <switches> <header arguments> <body> -#+end_src +#+END_SRC @end example -Switches and header arguments are optional. Code can also be embedded in text -inline using +The @code{#+NAME:} line is optional, and can be used to name the code +block. Live code blocks require that a language be specified on the +@code{#+BEGIN_SRC} line. Switches and header arguments are optional. +@cindex source code, inline + +Live code blocks can also be specified inline using @example src_<language>@{<body>@} @@ -11647,26 +12469,30 @@ src_<language>[<header arguments>]@{<body>@} @end example @table @code -@item <name> -This name is associated with the code block. This is similar to the -@samp{#+tblname} lines that can be used to name tables in Org-mode files. -Referencing the name of a code block makes it possible to evaluate the -block from other places in the file, other files, or from Org-mode table -formulas (see @ref{The spreadsheet}). Names are assumed to be unique by -evaluation functions and the behavior of multiple blocks of the same name is +@item <#+NAME: name> +This line associates a name with the code block. This is similar to the +@code{#+TBLNAME: NAME} lines that can be used to name tables in Org mode +files. Referencing the name of a code block makes it possible to evaluate +the block from other places in the file, from other files, or from Org mode +table formulas (see @ref{The spreadsheet}). Names are assumed to be unique +and the behavior of Org mode when two or more blocks share the same name is undefined. +@cindex #+NAME @item <language> -The language of the code in the block. +The language of the code in the block (see @ref{Languages}). +@cindex source code, language @item <switches> -Optional switches controlling exportation of the code block (see switches discussion in +Optional switches control code block export (see the discussion of switches in @ref{Literal examples}) +@cindex source code, switches @item <header arguments> Optional header arguments control many aspects of evaluation, export and -tangling of code blocks. See the @ref{Header arguments}. +tangling of code blocks (see @ref{Header arguments}). Header arguments can also be set on a per-buffer or per-subtree basis using properties. +@item source code, header arguments @item <body> -The source code. +Source code in the specified language. @end table @comment node-name, next, previous, up @@ -11715,12 +12541,12 @@ variable @code{org-src-fontify-natively}. @cindex code block, exporting @cindex source code, exporting -It is possible to export the @emph{contents} of code blocks, the -@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For -most languages, the default exports the contents of code blocks. However, for -some languages (e.g.@: @code{ditaa}) the default exports the results of code -block evaluation. For information on exporting code block bodies, see -@ref{Literal examples}. +It is possible to export the @emph{code} of code blocks, the @emph{results} +of code block evaluation, @emph{both} the code and the results of code block +evaluation, or @emph{none}. For most languages, the default exports code. +However, for some languages (e.g.@: @code{ditaa}) the default exports the +results of code block evaluation. For information on exporting code block +bodies, see @ref{Literal examples}. The @code{:exports} header argument can be used to specify export behavior: @@ -11732,7 +12558,7 @@ The default in most languages. The body of the code block is exported, as described in @ref{Literal examples}. @item :exports results The code block will be evaluated and the results will be placed in the -Org-mode buffer for export, either updating previous results of the code +Org mode buffer for export, either updating previous results of the code block located anywhere in the buffer or, if no previous results exist, placing the results immediately after the code block. The body of the code block will not be exported. @@ -11745,8 +12571,8 @@ Neither the code block nor its results will be exported. It is possible to inhibit the evaluation of code blocks during export. Setting the @code{org-export-babel-evaluate} variable to @code{nil} will ensure that no code blocks are evaluated as part of the export process. This -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 +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. @comment node-name, next, previous, up @@ -11798,14 +12624,15 @@ of tangled code files. @cindex source code, evaluating Code blocks can be evaluated@footnote{Whenever code is evaluated there is a -potential for that code to do harm. Org-mode provides a number of safeguards -to ensure that it only evaluates code with explicit confirmation from the -user. For information on these safeguards (and on how to disable them) see -@ref{Code evaluation security}.} and the results placed in the Org-mode -buffer. By default, evaluation is only turned on for @code{emacs-lisp} code -blocks, however support exists for evaluating blocks in many languages. See -@ref{Languages} for a list of supported languages. See @ref{Structure of -code blocks} for information on the syntax used to define a code block. +potential for that code to do harm. Org mode provides safeguards to ensure +that code is only evaluated after explicit confirmation from the user. For +information on these safeguards (and on how to disable them) see @ref{Code +evaluation security}.} and the results of evaluation optionally placed in the +Org mode buffer. By default, the evaluation facility is only enabled for +Lisp code blocks specified as @code{emacs-lisp}. However, souce code blocks +in many languages can be evaluated within Org mode (see @ref{Languages} for a +list of supported languages and @ref{Structure of code blocks} for +information on the syntax used to define a code block). @kindex C-c C-c There are a number of ways to evaluate code blocks. The simplest is to press @@ -11813,64 +12640,52 @@ There are a number of ways to evaluate code blocks. The simplest is to press @code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code evaluation from the @kbd{C-c C-c} key binding.}. This will call the @code{org-babel-execute-src-block} function to evaluate the block and insert -its results into the Org-mode buffer. +its results into the Org mode buffer. +@cindex #+CALL It is also possible to evaluate named code blocks from anywhere in an -Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously -@code{#+function} or @code{#+lob}) lines can be used to remotely execute code -blocks located in the current Org-mode buffer or in the ``Library of Babel'' -(see @ref{Library of Babel}). These lines use the following syntax to place -a call on a line by itself. +Org mode buffer or an Org mode table. Live code blocks located in the current +Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel}) +can be executed. Named code blocks can be executed with a separate +@code{#+CALL:} line or inline within a block of text. + +The syntax of the @code{#+CALL:} line is @example -#+call: <name>(<arguments>) -#+call: <name>[<header args>](<arguments>) <header args> +#+CALL: <name>(<arguments>) +#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments> @end example -The following syntax can be used to place these calls within a block of -prose. +The syntax for inline evaluation of named code blocks is @example -...prose... call_<name>(<arguments>) ...prose... -...prose... call_<name>[<header args>](<arguments>)[<header args>] ...prose... +... call_<name>(<arguments>) ... +... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ... @end example @table @code @item <name> -The name of the code block to be evaluated. +The name of the code block to be evaluated (see @ref{Structure of code blocks}). @item <arguments> Arguments specified in this section will be passed to the code block. These -arguments should relate to @code{:var} header arguments in the called code -block expressed using standard function call syntax. For example if the -original code block named @code{double} has the header argument @code{:var -n=2}, then the call line passing the number four to that block would be -written as @code{#+call: double(n=2)}. -@item <header args> -Header arguments can be placed either inside the call to the code block or at -the end of the line as shown below. - -@example -#+call: code_bloc_name[XXXX](arguments) YYYY -@end example - -Header arguments located in these two locations are treated differently. - -@table @code -@item XXXX -Those placed in the @code{XXXX} location are passed through and applied to -the code block being called. These header arguments affect how the code -block is evaluated, for example @code{[:results output]} will collect the -results from @code{STDOUT} of the called code block. -@item YYYY -Those placed in the @code{YYYY} location are applied to the call line and do -not affect the code block being called. These header arguments affect how -the results are incorporated into the Org-mode buffer when the call line is -evaluated, and how the call line is exported. For example @code{:results -org} at the end of the call line will insert the results of the call line -inside of an Org-mode block. -@end table - -For more examples of passing header arguments to @code{#+call:} lines see +arguments use standard function call syntax, rather than +header argument syntax. For example, a @code{#+CALL:} line that passes the +number four to a code block named @code{double}, which declares the header +argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}. +@item <inside header arguments> +Inside header arguments are passed through and applied to the named code +block. These arguments use header argument syntax rather than standard +function call syntax. Inside header arguments affect how the code block is +evaluated. For example, @code{[:results output]} will collect the results of +everything printed to @code{STDOUT} during execution of the code block. +@item <end header arguments> +End header arguments are applied to the calling instance and do not affect +evaluation of the named code block. They affect how the results are +incorporated into the Org mode buffer and how the call line is exported. For +example, @code{:results html} will insert the results of the call line +evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block. + +For more examples of passing header arguments to @code{#+CALL:} lines see @ref{Header arguments in function calls}. @end table @@ -11880,18 +12695,22 @@ For more examples of passing header arguments to @code{#+call:} lines see @cindex source code, library @cindex code block, library -The ``Library of Babel'' is a library of code blocks -that can be called from any Org-mode file. The library is housed in an -Org-mode file located in the @samp{contrib} directory of Org-mode. -Org-mode users can deposit functions they believe to be generally -useful in the library. +The ``Library of Babel'' consists of code blocks that can be called from any +Org mode file. Code blocks defined in the ``Library of Babel'' can be called +remotely as if they were in the current Org mode buffer (see @ref{Evaluating +code blocks} for information on the syntax of remote code block evaluation). + + +The central repository of code blocks in the ``Library of Babel'' is housed +in an Org mode file located in the @samp{contrib} directory of Org mode. + +Users can add code blocks they believe to be generally useful to their +``Library of Babel.'' The code blocks can be stored in any Org mode file and +then loaded into the library with @code{org-babel-lob-ingest}. -Code blocks defined in the ``Library of Babel'' can be called remotely as if -they were in the current Org-mode buffer (see @ref{Evaluating code blocks} -for information on the syntax of remote code block evaluation). @kindex C-c C-v i -Code blocks located in any Org-mode file can be loaded into the ``Library of +Code blocks located in any Org mode file can be loaded into the ``Library of Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v i}. @@ -11916,7 +12735,7 @@ Code blocks in the following languages are supported. @item Ledger @tab ledger @tab Lisp @tab lisp @item Lilypond @tab lilypond @tab MATLAB @tab matlab @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml -@item Octave @tab octave @tab Org-mode @tab org +@item Octave @tab octave @tab Org mode @tab org @item Oz @tab oz @tab Perl @tab perl @item Plantuml @tab plantuml @tab Python @tab python @item R @tab R @tab Ruby @tab ruby @@ -11980,7 +12799,7 @@ specific (and having higher priority) than the last. * System-wide header arguments:: Set global default values * Language-specific header arguments:: Set default values by language * Buffer-wide header arguments:: Set default values for a specific buffer -* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Header arguments in Org mode properties:: Set 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 @end menu @@ -12031,12 +12850,11 @@ Each language can define its own set of default header arguments. See the language-specific documentation available online at @uref{http://orgmode.org/worg/org-contrib/babel}. -@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments +@node Buffer-wide header arguments, Header arguments in Org mode properties, Language-specific header arguments, Using header arguments @subsubheading Buffer-wide header arguments -Buffer-wide header arguments may be specified through the use of a special -line placed anywhere in an Org-mode file. The line consists of the -@code{#+BABEL:} keyword followed by a series of header arguments which may be -specified using the standard header argument syntax. +Buffer-wide header arguments may be specified as properties through the use +of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see +@ref{Property syntax}). For example the following would set @code{session} to @code{*R*}, and @code{results} to @code{silent} for every code block in the buffer, ensuring @@ -12044,24 +12862,27 @@ that all execution took place in the same session, and no results would be inserted into the buffer. @example -#+BABEL: :session *R* :results silent +#+PROPERTY: session *R* +#+PROPERTY: results silent @end example -@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments -@subsubheading Header arguments in Org-mode properties +@node Header arguments in Org mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments +@subsubheading Header arguments in Org mode properties -Header arguments are also read from Org-mode properties (see @ref{Property +Header arguments are also read from Org mode properties (see @ref{Property syntax}), which can be set on a buffer-wide or per-heading basis. An example of setting a header argument for all code blocks in a buffer is @example -#+property: tangle yes +#+PROPERTY: tangle yes @end example +@vindex org-use-property-inheritance When properties are used to set default header arguments, they are looked up -with inheritance, so the value of the @code{:cache} header argument will default -to @code{yes} in all code blocks in the subtree rooted at the following -heading: +with inheritance, regardless of the value of +@code{org-use-property-inheritance}. In the following example the value of +the @code{:cache} header argument will default to @code{yes} in all code +blocks in the subtree rooted at the following heading: @example * outline header @@ -12075,45 +12896,47 @@ heading: Properties defined in this way override the properties set in @code{org-babel-default-header-args}. It is convenient to use the @code{org-set-property} function bound to @kbd{C-c C-x p} to set properties -in Org-mode documents. +in Org mode documents. -@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org-mode properties, Using header arguments +@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org mode properties, Using header arguments @subsubheading Code block specific header arguments The most common way to assign values to header arguments is at the code block level. This can be done by listing a sequence of header -arguments and their values as part of the @code{#+begin_src} line. +arguments and their values as part of the @code{#+BEGIN_SRC} line. Properties set in this way override both the values of @code{org-babel-default-header-args} and header arguments specified as properties. In the following example, the @code{:results} header argument is set to @code{silent}, meaning the results of execution will not be inserted in the buffer, and the @code{:exports} header argument is set to @code{code}, meaning only the body of the code block will be -preserved on export to HTML or LaTeX. +preserved on export to HTML or @LaTeX{}. @example -#+source: factorial -#+begin_src haskell :results silent :exports code :var n=0 +#+NAME: factorial +#+BEGIN_SRC haskell :results silent :exports code :var n=0 fac 0 = 1 fac n = n * fac (n-1) -#+end_src +#+END_SRC @end example -Similarly, it is possible to set header arguments for inline code blocks: +Similarly, it is possible to set header arguments for inline code blocks @example src_haskell[:exports both]@{fac 5@} @end example -Code block header arguments can span multiple lines using =#+header:= or -=#+headers:= lines preceding a code block or nested in between the name and -body of a named code block. +Code block header arguments can span multiple lines using @code{#+HEADER:} or +@code{#+HEADERS:} lines preceding a code block or nested between the +@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block. +@cindex #+HEADER: +@cindex #+HEADERS: Multi-line header arguments on an un-named code block: @example - #+headers: :var data1=1 - #+begin_src emacs-lisp :var data2=2 + #+HEADERS: :var data1=1 + #+BEGIN_SRC emacs-lisp :var data2=2 (message "data1:%S, data2:%S" data1 data2) - #+end_src + #+END_SRC #+results: : data1:1, data2:2 @@ -12121,11 +12944,11 @@ Multi-line header arguments on an un-named code block: Multi-line header arguments on a named code block: @example - #+source: named-block - #+header: :var data=2 - #+begin_src emacs-lisp + #+NAME: named-block + #+HEADER: :var data=2 + #+BEGIN_SRC emacs-lisp (message "data:%S" data) - #+end_src + #+END_SRC #+results: named-block : data:2 @@ -12136,25 +12959,26 @@ Multi-line header arguments on a named code block: @subsubheading Header arguments in function calls At the most specific level, header arguments for ``Library of Babel'' or -function call lines can be set as shown in the two examples below. For more -information on the structure of @code{#+call:} lines see @ref{Evaluating code +@code{#+CALL:} lines can be set as shown in the two examples below. For more +information on the structure of @code{#+CALL:} lines see @ref{Evaluating code blocks}. The following will apply the @code{:exports results} header argument to the -evaluation of the @code{#+call:} line. +evaluation of the @code{#+CALL:} line. @example -#+call: factorial(n=5) :exports results +#+CALL: factorial(n=5) :exports results @end example The following will apply the @code{:session special} header argument to the evaluation of the @code{factorial} code block. @example -#+call: factorial[:session special](n=5) +#+CALL: factorial[:session special](n=5) @end example @node Specific header arguments, , Using header arguments, Header arguments @subsection Specific header arguments -The following header arguments are defined: +Header arguments consist of an initial colon followed by the name of the +argument in lowercase letters. The following header arguments are defined: @menu * var:: Pass arguments to code blocks @@ -12193,13 +13017,18 @@ Additional header arguments are defined on a language-specific basis, see The @code{:var} header argument is used to pass arguments to code blocks. The specifics of how arguments are included in a code block vary by language; these are addressed in the language-specific documentation. However, the -syntax used to specify arguments is the same across all languages. The -values passed to arguments can be literal values, values from org-mode tables -and literal example blocks, the results of other code blocks, or Emacs Lisp -code---see the ``Emacs Lisp evaluation of variables'' heading below. +syntax used to specify arguments is the same across all languages. In every +case, variables require a default value when they are declared. + +The values passed to arguments can either be literal values, references, or +Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References +include anything in the Org mode file that takes a @code{#+NAME:}, +@code{#+TBLNAME:}, or @code{#+RESULTS:} line. This includes tables, lists, +@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other +code blocks. -These values can be indexed in a manner similar to arrays---see the -``indexable variable values'' heading below. +Argument values can be indexed in a manner similar to arrays (see @ref{var, +Indexable variable values}). The following syntax is used to pass arguments to code blocks using the @code{:var} header argument. @@ -12208,76 +13037,122 @@ The following syntax is used to pass arguments to code blocks using the :var name=assign @end example -where @code{assign} can take one of the following forms +The argument, @code{assign}, can either be a literal value, such as a string +@samp{"string"} or a number @samp{9}, or a reference to a table, a list, a +literal example, another code block (with or without arguments), or the +results of evaluating another code block. -@itemize @bullet -@item literal value -either a string @code{"string"} or a number @code{9}. -@item reference -a table name: +Here are examples of passing values by reference: + +@table @dfn +@item table +an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line @example -#+tblname: example-table +#+TBLNAME: example-table | 1 | | 2 | | 3 | | 4 | -#+source: table-length -#+begin_src emacs-lisp :var table=example-table +#+NAME: table-length +#+BEGIN_SRC emacs-lisp :var table=example-table (length table) -#+end_src +#+END_SRC #+results: table-length : 4 @end example -a code block name, as assigned by @code{#+srcname:}, followed by -parentheses: +@item list +a simple list named with a @code{#+NAME:} line (note that nesting is not +carried through to the source code block) @example -#+begin_src emacs-lisp :var length=table-length() +#+NAME: example-list + - simple + - not + - nested + - list + +#+BEGIN_SRC emacs-lisp :var x=example-list + (print x) +#+END_SRC + +#+results: +| simple | list | +@end example + +@item code block without arguments +a code block name (from the example above), as assigned by @code{#+NAME:}, +optionally followed by parentheses + +@example +#+BEGIN_SRC emacs-lisp :var length=table-length() (* 2 length) -#+end_src +#+END_SRC #+results: : 8 @end example -In addition, an argument can be passed to the code block referenced -by @code{:var}. The argument is passed within the parentheses following the -code block name: +@item code block with arguments +a code block name, as assigned by @code{#+NAME:}, followed by parentheses and +optional arguments passed within the parentheses following the +code block name using standard function call syntax @example -#+source: double -#+begin_src emacs-lisp :var input=8 +#+NAME: double +#+BEGIN_SRC emacs-lisp :var input=8 (* 2 input) -#+end_src +#+END_SRC #+results: double : 16 -#+source: squared -#+begin_src emacs-lisp :var input=double(input=1) +#+NAME: squared +#+BEGIN_SRC emacs-lisp :var input=double(input=1) (* input input) -#+end_src +#+END_SRC #+results: squared : 4 @end example -@end itemize + +@item literal example +a literal example block named with a @code{#+NAME:} line + +@example +#+NAME: literal-example +#+BEGIN_EXAMPLE +A literal example +on two lines +#+END_EXAMPLE + +#+NAME: read-literal-example +#+BEGIN_SRC emacs-lisp :var x=literal-example + (concatenate 'string x " for you.") +#+END_SRC + +#+results: read-literal-example +: A literal example +: on two lines for you. + +@end example + +@end table @subsubheading Alternate argument syntax It is also possible to specify arguments in a potentially more natural way -using the @code{#+source:} line of a code block. As in the following -example arguments can be packed inside of parenthesis, separated by commas, +using the @code{#+NAME:} line of a code block. As in the following +example, arguments can be packed inside of parentheses, separated by commas, following the source name. @example -#+source: double(input=0, x=2) -#+begin_src emacs-lisp +#+NAME: double(input=0, x=2) +#+BEGIN_SRC emacs-lisp (* 2 (+ input x)) -#+end_src +#+END_SRC @end example @subsubheading Indexable variable values @@ -12291,15 +13166,15 @@ following example assigns the last cell of the first row the table @code{example-table} to the variable @code{data}: @example -#+results: example-table +#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | -#+begin_src emacs-lisp :var data=example-table[0,-1] +#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1] data -#+end_src +#+END_SRC #+results: : a @@ -12311,16 +13186,16 @@ example the following assigns the middle three rows of @code{example-table} to @code{data}. @example -#+results: example-table +#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | | 5 | 3 | -#+begin_src emacs-lisp :var data=example-table[1:3] +#+BEGIN_SRC emacs-lisp :var data=example-table[1:3] data -#+end_src +#+END_SRC #+results: | 2 | b | @@ -12334,15 +13209,15 @@ interpreted to mean the entire range and as such are equivalent to column is referenced. @example -#+results: example-table +#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | -#+begin_src emacs-lisp :var data=example-table[,0] +#+BEGIN_SRC emacs-lisp :var data=example-table[,0] data -#+end_src +#+END_SRC #+results: | 1 | 2 | 3 | 4 | @@ -12353,16 +13228,16 @@ Any number of dimensions can be indexed. Dimensions are separated from one another by commas, as shown in the following example. @example -#+source: 3D -#+begin_src emacs-lisp +#+NAME: 3D +#+BEGIN_SRC emacs-lisp '(((1 2 3) (4 5 6) (7 8 9)) ((10 11 12) (13 14 15) (16 17 18)) ((19 20 21) (22 23 24) (25 26 27))) -#+end_src +#+END_SRC -#+begin_src emacs-lisp :var data=3D[1,,1] +#+BEGIN_SRC emacs-lisp :var data=3D[1,,1] data -#+end_src +#+END_SRC #+results: | 11 | 14 | 17 | @@ -12371,31 +13246,31 @@ another by commas, as shown in the following example. @subsubheading Emacs Lisp evaluation of variables Emacs lisp code can be used to initialize variable values. When a variable -value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be evaluated as -Emacs Lisp and the result of the evaluation will be assigned as the variable -value. The following example demonstrates use of this evaluation to reliably -pass the file-name of the org-mode buffer to a code block---note that -evaluation of header arguments is guaranteed to take place in the original -org-mode file, while there is no such guarantee for evaluation of the code -block body. +value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be +evaluated as Emacs Lisp and the result of the evaluation will be assigned as +the variable value. The following example demonstrates use of this +evaluation to reliably pass the file-name of the Org mode buffer to a code +block---note that evaluation of header arguments is guaranteed to take place +in the original Org mode file, while there is no such guarantee for +evaluation of the code block body. @example -#+begin_src sh :var filename=(buffer-file-name) :exports both +#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both wc -w $filename -#+end_src +#+END_SRC @end example Note that values read from tables and lists will not be evaluated as Emacs Lisp, as shown in the following example. @example -#+results: table +#+NAME: table | (a b c) | -#+headers: :var data=table[0,0] -#+begin_src perl +#+HEADERS: :var data=table[0,0] +#+BEGIN_SRC perl $data -#+end_src +#+END_SRC #+results: : (a b c) @@ -12414,7 +13289,7 @@ from the code block @item @b{type} header arguments specify what type of result the code block will return---which has implications for how they will be inserted into the -Org-mode buffer +Org mode buffer @item @b{handling} header arguments specify how the results of evaluating the code block should be handled. @@ -12445,31 +13320,31 @@ table or scalar depending on their value. @itemize @bullet @item @code{table}, @code{vector} -The results should be interpreted as an Org-mode table. If a single value is +The results should be interpreted as an Org mode table. If a single value is returned, it will be converted into a table with one row and one column. E.g., @code{:results value table}. @item @code{list} -The results should be interpreted as an Org-mode list. If a single scalar +The results should be interpreted as an Org mode list. If a single scalar value is returned it will be converted into a list with only one element. @item @code{scalar}, @code{verbatim} The results should be interpreted literally---they will not be -converted into a table. The results will be inserted into the Org-mode +converted into a table. The results will be inserted into the Org mode buffer as quoted text. E.g., @code{:results value verbatim}. @item @code{file} The results will be interpreted as the path to a file, and will be inserted -into the Org-mode buffer as a file link. E.g., @code{:results value file}. +into the Org mode buffer as a file link. E.g., @code{:results value file}. @item @code{raw}, @code{org} -The results are interpreted as raw Org-mode code and are inserted directly +The results are interpreted as raw Org mode code and are inserted directly into the buffer. If the results look like a table they will be aligned as -such by Org-mode. E.g., @code{:results value raw}. +such by Org mode. E.g., @code{:results value raw}. @item @code{html} Results are assumed to be HTML and will be enclosed in a @code{begin_html} block. E.g., @code{:results value html}. @item @code{latex} -Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. +Results assumed to be @LaTeX{} and are enclosed in a @code{begin_latex} block. E.g., @code{:results value latex}. @item @code{code} -Result are assumed to be parseable code and are enclosed in a code block. +Result are assumed to be parsable code and are enclosed in a code block. E.g., @code{:results value code}. @item @code{pp} The result is converted to pretty-printed code and is enclosed in a code @@ -12488,10 +13363,10 @@ results once they are collected. @itemize @bullet @item @code{silent} The results will be echoed in the minibuffer but will not be inserted into -the Org-mode buffer. E.g., @code{:results output silent}. +the Org mode buffer. E.g., @code{:results output silent}. @item @code{replace} The default value. Any existing results will be removed, and the new results -will be inserted into the Org-mode buffer in their place. E.g., +will be inserted into the Org mode buffer in their place. E.g., @code{:results output replace}. @item @code{append} If there are pre-existing results of the code block then the new results will @@ -12507,9 +13382,9 @@ inserted as with @code{replace}. @subsubsection @code{:file} The header argument @code{:file} is used to specify an external file in which -to save code block results. After code block evaluation an Org-mode style +to save code block results. After code block evaluation an Org mode style @code{[[file:]]} link (see @ref{Link format}) to the file will be inserted -into the Org-mode buffer. Some languages including R, gnuplot, dot, and +into the Org mode buffer. Some languages including R, gnuplot, dot, and ditaa provide special handling of the @code{:file} header argument automatically wrapping the code block body in the boilerplate code required to save output to the specified file. This is often useful for saving @@ -12538,9 +13413,9 @@ In other words, if you want your plot to go into a folder called @file{Work} in your home directory, you could use @example -#+begin_src R :file myplot.png :dir ~/Work +#+BEGIN_SRC R :file myplot.png :dir ~/Work matplot(matrix(rnorm(100), 10), type="l") -#+end_src +#+END_SRC @end example @subsubheading Remote execution @@ -12548,14 +13423,14 @@ A directory on a remote machine can be specified using tramp file syntax, in which case the code will be evaluated on the remote machine. An example is @example -#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: +#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu: plot(1:10, main=system("hostname", intern=TRUE)) -#+end_src +#+END_SRC @end example -Text results will be returned to the local Org-mode buffer as usual, and file +Text results will be returned to the local Org mode buffer as usual, and file output will be created on the remote machine with relative paths interpreted -relative to the remote directory. An Org-mode link to the remote file will be +relative to the remote directory. An Org mode link to the remote file will be created. So, in the above example a plot will be created on the remote machine, @@ -12581,7 +13456,7 @@ currently made to alter the directory associated with an existing session. @code{:dir} should typically not be used to create files during export with @code{:exports results} or @code{:exports both}. The reason is that, in order to retain portability of exported material between machines, during export -links inserted into the buffer will *not* be expanded against @code{default +links inserted into the buffer will @emph{not} be expanded against @code{default directory}. Therefore, if @code{default-directory} is altered using @code{:dir}, it is probable that the file will be created in a location to which the link does not point. @@ -12591,7 +13466,7 @@ which the link does not point. @subsubsection @code{:exports} The @code{:exports} header argument specifies what should be included in HTML -or LaTeX exports of the Org-mode file. +or @LaTeX{} exports of the Org mode file. @itemize @bullet @item @code{code} @@ -12616,14 +13491,14 @@ block should be included in tangled extraction of source code files. @itemize @bullet @item @code{tangle} The code block is exported to a source code file named after the full path -(including the directory) and file name (w/o extension) of the Org-mode file. +(including the directory) and file name (w/o extension) of the Org mode file. E.g., @code{:tangle yes}. @item @code{no} The default. The code block is not exported to a source code file. E.g., @code{:tangle no}. @item other Any other string passed to the @code{:tangle} header argument is interpreted -as a path (directory and file name relative to the directory of the Org-mode +as a path (directory and file name relative to the directory of the Org mode file) to which the block will be exported. E.g., @code{:tangle path}. @end itemize @@ -12650,7 +13525,7 @@ original Org file from which the code was tangled. @item @code{yes} A synonym for ``link'' to maintain backwards compatibility. @item @code{org} -Include text from the org-mode file as a comment. +Include text from the Org mode file as a comment. The text is picked from the leading context of the tangled code and is limited by the nearest headline or source block as the case may be. @@ -12751,37 +13626,39 @@ concatenated together to form the replacement text. By setting this header argument at the sub-tree or file level, simple code block concatenation may be achieved. For example, when tangling the -following Org-mode file, the bodies of code blocks will be concatenated into -the resulting pure code file. +following Org mode file, the bodies of code blocks will be concatenated into +the resulting pure code file@footnote{(The example needs property inheritance +to be turned on for the @code{noweb-ref} property, see @ref{Property +inheritance}).}. @example - #+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh + #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh <<fullest-disk>> - #+end_src + #+END_SRC * the mount point of the fullest disk :PROPERTIES: :noweb-ref: fullest-disk :END: ** query all mounted disks - #+begin_src sh + #+BEGIN_SRC sh df \ - #+end_src + #+END_SRC ** strip the header row - #+begin_src sh + #+BEGIN_SRC sh |sed '1d' \ - #+end_src + #+END_SRC ** sort by the percent full - #+begin_src sh + #+BEGIN_SRC sh |awk '@{print $5 " " $6@}'|sort -n |tail -1 \ - #+end_src + #+END_SRC ** extract the mount point - #+begin_src sh + #+BEGIN_SRC sh |awk '@{print $2@}' - #+end_src + #+END_SRC @end example @node cache, sep, noweb-ref, Specific header arguments @@ -12811,18 +13688,18 @@ invalidated and the code block is re-run. In the following example, changed since it was last run. @example - #+srcname: random - #+begin_src R :cache yes + #+NAME: random + #+BEGIN_SRC R :cache yes runif(1) - #+end_src + #+END_SRC #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random 0.4659510825295 - #+srcname: caller - #+begin_src emacs-lisp :var x=random :cache yes + #+NAME: caller + #+BEGIN_SRC emacs-lisp :var x=random :cache yes x - #+end_src + #+END_SRC #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller 0.254227238707244 @@ -12832,7 +13709,7 @@ changed since it was last run. @subsubsection @code{:sep} The @code{:sep} header argument can be used to control the delimiter used -when writing tabular results out to files external to Org-mode. This is used +when writing tabular results out to files external to Org mode. This is used either when opening tabular results of a code block by calling the @code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block, or when writing code block results to an external file (see @ref{file}) @@ -12856,17 +13733,17 @@ variable and raises an error. Setting @code{:hlines no} or relying on the default value yields the following results. @example -#+tblname: many-cols +#+TBLNAME: many-cols | a | b | c | |---+---+---| | d | e | f | |---+---+---| | g | h | i | -#+source: echo-table -#+begin_src python :var tab=many-cols +#+NAME: echo-table +#+BEGIN_SRC python :var tab=many-cols return tab -#+end_src +#+END_SRC #+results: echo-table | a | b | c | @@ -12878,17 +13755,17 @@ default value yields the following results. Leaves hlines in the table. Setting @code{:hlines yes} has this effect. @example -#+tblname: many-cols +#+TBLNAME: many-cols | a | b | c | |---+---+---| | d | e | f | |---+---+---| | g | h | i | -#+source: echo-table -#+begin_src python :var tab=many-cols :hlines yes +#+NAME: echo-table +#+BEGIN_SRC python :var tab=many-cols :hlines yes return tab -#+end_src +#+END_SRC #+results: echo-table | a | b | c | @@ -12904,6 +13781,10 @@ Leaves hlines in the table. Setting @code{:hlines yes} has this effect. The @code{:colnames} header argument accepts the values @code{yes}, @code{no}, or @code{nil} for unassigned. The default value is @code{nil}. +Note that the behavior of the @code{:colnames} header argument may differ +across languages. For example Emacs Lisp code blocks ignore the +@code{:colnames} header argument entirely given the ease with which tables +with column names may be handled directly in Emacs Lisp. @itemize @bullet @item @code{nil} @@ -12913,16 +13794,16 @@ names will be removed from the table before processing, then reapplied to the results. @example -#+tblname: less-cols +#+TBLNAME: less-cols | a | |---| | b | | c | -#+srcname: echo-table-again -#+begin_src python :var tab=less-cols +#+NAME: echo-table-again +#+BEGIN_SRC python :var tab=less-cols return [[val + '*' for val in row] for row in tab] -#+end_src +#+END_SRC #+results: echo-table-again | a | @@ -12958,14 +13839,14 @@ The first column of the table is removed from the table before processing, and is then reapplied to the results. @example -#+tblname: with-rownames +#+TBLNAME: with-rownames | one | 1 | 2 | 3 | 4 | 5 | | two | 6 | 7 | 8 | 9 | 10 | -#+srcname: echo-table-once-again -#+begin_src python :var tab=with-rownames :rownames yes +#+NAME: echo-table-once-again +#+BEGIN_SRC python :var tab=with-rownames :rownames yes return [[val + 10 for val in row] for row in tab] -#+end_src +#+END_SRC #+results: echo-table-once-again | one | 11 | 12 | 13 | 14 | 15 | @@ -12988,12 +13869,23 @@ permissions of the tangled file are set to make it executable. @node eval, , shebang, Specific header arguments @subsubsection @code{:eval} The @code{:eval} header argument can be used to limit the evaluation of -specific code blocks. @code{:eval} accepts two arguments ``never'' and -``query''. @code{:eval never} will ensure that a code block is never -evaluated, this can be useful for protecting against the evaluation of -dangerous code blocks. @code{:eval query} will require a query for every -execution of a code block regardless of the value of the -@code{org-confirm-babel-evaluate} variable. +specific code blocks. The @code{:eval} header argument can be useful for +protecting against the evaluation of dangerous code blocks or to ensure that +evaluation will require a query regardless of the value of the +@code{org-confirm-babel-evaluate} variable. The possible values of +@code{:eval} and their effects are shown below. + +@table @code +@item never or no +The code block will not be evaluated under any circumstances. +@item query +Evaluation of the code block will require a query. +@item never-export or no-export +The code block will not be evaluated during export but may still be called +interactively. +@item query-export +Evaluation of the code block during export will require a query. +@end table If this header argument is not set then evaluation is determined by the value of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation @@ -13016,7 +13908,7 @@ of the possible results header arguments see @ref{results}. @end multitable Note: With @code{:results value}, the result in both @code{:session} and -non-session is returned to Org-mode as a table (a one- or two-dimensional +non-session is returned to Org mode as a table (a one- or two-dimensional vector of strings or numbers) when appropriate. @subsection Non-session @@ -13062,26 +13954,26 @@ were passed to a non-interactive interpreter running as an external process. For example, compare the following two blocks: @example -#+begin_src python :results output +#+BEGIN_SRC python :results output print "hello" 2 print "bye" -#+end_src +#+END_SRC -#+resname: +#+results: : hello : bye @end example In non-session mode, the `2' is not printed and does not appear. @example -#+begin_src python :results output :session +#+BEGIN_SRC python :results output :session print "hello" 2 print "bye" -#+end_src +#+END_SRC -#+resname: +#+results: : hello : 2 : bye @@ -13109,7 +14001,8 @@ When a code block is tangled or evaluated, whether or not ``noweb'' references are expanded depends upon the value of the @code{:noweb} header argument. If @code{:noweb yes}, then a Noweb reference is expanded before evaluation. If @code{:noweb no}, the default, then the reference is not -expanded before evaluation. +expanded before evaluation. See the @ref{noweb-ref} header argument for +a more flexible way to resolve noweb references. Note: the default value, @code{:noweb no}, was chosen to ensure that correct code is not broken in a language, such as Ruby, where @@ -13117,11 +14010,17 @@ correct code is not broken in a language, such as Ruby, where syntactically valid in languages that you use, then please consider setting the default value. +Note: if noweb tangling is slow in large Org-mode files consider setting the +@code{*org-babel-use-quick-and-dirty-noweb-expansion*} variable to true. +This will result in faster noweb reference resolution at the expense of not +correctly resolving inherited values of the @code{:noweb-ref} header +argument. + @node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code @section Key bindings and useful functions @cindex code block, key bindings -Many common Org-mode key sequences are re-bound depending on +Many common Org mode key sequences are re-bound depending on the context. Within a code block, the following key bindings @@ -13138,7 +14037,7 @@ are active: @item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session} @end multitable -In an Org-mode buffer, the following key bindings are active: +In an Org mode buffer, the following key bindings are active: @multitable @columnfractions 0.45 0.55 @kindex C-c C-v a @@ -13255,7 +14154,7 @@ emacs -Q --batch -l $ORGINSTALL \ @cindex tag completion @cindex link abbreviations, completion of -Emacs would not be Emacs without completion, and Org-mode uses it whenever it +Emacs would not be Emacs without completion, and Org mode uses it whenever it makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for some of the completion prompts, you can specify your preference by setting at most one of the variables @code{org-completion-use-iswitchb} @@ -13290,7 +14189,7 @@ buffer. After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). @item After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or -@samp{OPTIONS} which set file-specific options for Org-mode. When the +@samp{OPTIONS} which set file-specific options for Org mode. When the option keyword is already complete, pressing @kbd{M-@key{TAB}} again will insert example settings for this keyword. @item @@ -13306,7 +14205,7 @@ Elsewhere, complete dictionary words using Ispell. @cindex template insertion @cindex insertion, of templates -Org-mode supports insertion of empty structural elements (like +Org mode supports insertion of empty structural elements (like @code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key strokes. This is achieved through a native template expansion mechanism. Note that Emacs has several other template mechanisms which could be used in @@ -13438,7 +14337,7 @@ lines into the buffer (@pxref{In-buffer settings}). @cindex in-buffer settings @cindex special keywords -Org-mode uses special lines in the buffer to define settings on a +Org mode uses special lines in the buffer to define settings on a per-file basis. These lines start with a @samp{#+} followed by a keyword, a colon, and then individual words defining a setting. Several setting words can be in the same line, but you can also have multiple @@ -13497,14 +14396,14 @@ buffer, most useful for specifying the allowed values of a property. @item #+SETUPFILE: file This line defines a file that holds more in-buffer setup. Normally this is entirely ignored. Only when the buffer is parsed for option-setting lines -(i.e.@: when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a +(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a settings line, or when exporting), then the contents of this file are parsed as if they had been included in the buffer. In particular, the file can be -any other Org-mode file with internal setup. You can visit the file the +any other Org mode file with internal setup. You can visit the file the cursor is in the line with @kbd{C-c '}. @item #+STARTUP: @cindex #+STARTUP: -This line sets options to be used at startup of Org-mode, when an +This line sets options to be used at startup of Org mode, when an Org file is being visited. The first set of options deals with the initial visibility of the outline @@ -13527,7 +14426,7 @@ showeverything @r{show even drawer contents} @cindex @code{indent}, STARTUP keyword @cindex @code{noindent}, STARTUP keyword Dynamic virtual indentation is controlled by the variable -@code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required} +@code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required} @example indent @r{start with @code{org-indent-mode} turned on} noindent @r{start with @code{org-indent-mode} turned off} @@ -13748,6 +14647,8 @@ ordered list. @item If the cursor is on the @code{#+BEGIN} line of a dynamic block, the block is updated. +@item +If the cursor is at a timestamp, fix the day name in the timestamp. @end itemize @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous @@ -13956,11 +14857,11 @@ setup. See the installation instructions in the file @item @file{cdlatex.el} by Carsten Dominik @cindex @file{cdlatex.el} @cindex Dominik, Carsten -Org-mode can make use of the CDLa@TeX{} package to efficiently enter +Org mode can make use of the CD@LaTeX{} package to efficiently enter @LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}. @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg @cindex @file{imenu.el} -Imenu allows menu access to an index of items in a file. Org-mode +Imenu allows menu access to an index of items in a file. Org mode supports Imenu---all you need to do to get the index is the following: @lisp (add-hook 'org-mode-hook @@ -13977,7 +14878,7 @@ Org used to use this package for capture, but no longer does. @cindex @file{speedbar.el} @cindex Ludlam, Eric M. Speedbar is a package that creates a special frame displaying files and -index items in files. Org-mode supports Speedbar and allows you to +index items in files. Org mode supports Speedbar and allows you to drill into Org files directly from the Speedbar. It also allows you to restrict the scope of agenda commands to a file or a subtree by using the command @kbd{<} in the Speedbar frame. @@ -13991,8 +14892,8 @@ the command @kbd{<} in the Speedbar frame. Complex ASCII tables with automatic line wrapping, column- and row-spanning, and alignment can be created using the Emacs table package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22). -Org-mode will recognize these tables and export them properly. Because of -interference with other Org-mode functionality, you unfortunately cannot edit +Org mode will recognize these tables and export them properly. Because of +interference with other Org mode functionality, you unfortunately cannot edit these tables directly in the buffer. Instead, you need to use the command @kbd{C-c '} to edit them, similar to source code snippets. @@ -14002,7 +14903,7 @@ Edit a @file{table.el} table. Works when the cursor is in a table.el table. @c @orgcmd{C-c ~,org-table-create-with-table.el} Insert a @file{table.el} table. If there is already a table at point, this -command converts it between the @file{table.el} format and the Org-mode +command converts it between the @file{table.el} format and the Org mode format. See the documentation string of the command @code{org-convert-table} for the restrictions under which this is possible. @@ -14011,13 +14912,13 @@ possible. @item @file{footnote.el} by Steven L. Baur @cindex @file{footnote.el} @cindex Baur, Steven L. -Org-mode recognizes numerical footnotes as provided by this package. -However, Org-mode also has its own footnote support (@pxref{Footnotes}), +Org mode recognizes numerical footnotes as provided by this package. +However, Org mode also has its own footnote support (@pxref{Footnotes}), which makes using @file{footnote.el} unnecessary. @end table @node Conflicts, , Cooperation, Interaction -@subsection Packages that lead to conflicts with Org-mode +@subsection Packages that lead to conflicts with Org mode @table @asis @@ -14029,7 +14930,7 @@ This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change timestamps, TODO keywords, priorities, and item bullet types if the cursor is at such a location. By default, @kbd{S-@key{cursor}} commands outside special contexts don't do anything, but you can customize the variable -@code{org-support-shift-select}. Org-mode then tries to accommodate shift +@code{org-support-shift-select}. Org mode then tries to accommodate shift selection by (i) using it outside of the special contexts where special commands apply, and by (ii) extending an existing active region even if the cursor moves across a special context. @@ -14044,7 +14945,7 @@ region. In fact, Emacs 23 has this built-in in the form of @code{shift-selection-mode}, see previous paragraph. If you are using Emacs 23, you probably don't want to use another package for this purpose. However, if you prefer to leave these keys to a different package while working in -Org-mode, configure the variable @code{org-replace-disputed-keys}. When set, +Org mode, configure the variable @code{org-replace-disputed-keys}. When set, Org will move the following key bindings in Org files, and in the agenda buffer (but not during date selection). @@ -14069,7 +14970,7 @@ fixed this problem: (add-hook 'org-mode-hook (lambda () (org-set-local 'yas/trigger-key [tab]) - (define-key yas/keymap [tab] 'yas/next-field-group))) + (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand))) @end lisp The latest version of yasnippet doesn't play well with Org mode. If the @@ -14096,7 +14997,7 @@ Then, tell Org mode what to do with the new function: @cindex @file{windmove.el} This package also uses the @kbd{S-<cursor>} keys, so everything written in the paragraph above about CUA mode also applies here. If you want make -the windmove function active in locations where Org-mode does not have +the windmove function active in locations where Org mode does not have special functionality on @kbd{S-@key{cursor}}, add this to your configuration: @@ -14112,7 +15013,7 @@ configuration: @cindex @file{viper.el} @kindex C-c / Viper uses @kbd{C-c /} and therefore makes this key not access the -corresponding Org-mode command @code{org-sparse-tree}. You need to find +corresponding Org mode command @code{org-sparse-tree}. You need to find another key for this command, or override the key in @code{viper-vi-global-user-map} with @@ -14197,7 +15098,7 @@ maintained by the Worg project and can be found at A large number of add-on packages have been written by various authors. These packages are not part of Emacs, but they are distributed as contributed -packages with the separate release available at the Org-mode home page at +packages with the separate release available at the Org mode home page at @uref{http://orgmode.org}. The list of contributed packages, along with documentation about each package, is maintained by the Worg project at @uref{http://orgmode.org/worg/org-contrib/}. @@ -14321,7 +15222,7 @@ Add-ons can tap into this functionality by providing a function that detects special context for that add-on and executes functionality appropriate for the context. Here is an example from Dan Davison's @file{org-R.el} which allows you to evaluate commands based on the @file{R} programming language -@footnote{@file{org-R.el} has been replaced by the org-mode functionality +@footnote{@file{org-R.el} has been replaced by the Org mode functionality described in @ref{Working With Source Code} and is now obsolete.}. For this package, special contexts are lines that start with @code{#+R:} or @code{#+RR:}. @@ -14374,12 +15275,12 @@ can use Org's facilities to edit and structure lists by turning @menu * Radio tables:: Sending and receiving radio tables -* A LaTeX example:: Step by step, almost a tutorial +* A @LaTeX{} example:: Step by step, almost a tutorial * Translator functions:: Copy and modify * Radio lists:: Doing the same for lists @end menu -@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax +@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax @subsection Radio tables @cindex radio tables @@ -14447,7 +15348,7 @@ makes this comment-toggling very easy, in particular if you bind it to a key. @end itemize -@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax +@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax @subsection A @LaTeX{} example of radio tables @cindex @LaTeX{}, and Orgtbl mode @@ -14557,7 +15458,7 @@ applied. Similar to @code{fmt}, functions of two arguments can be supplied instead of strings. @end table -@node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax +@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax @subsection Translator functions @cindex HTML, and Orgtbl mode @cindex translator function @@ -14877,7 +15778,7 @@ You may also modify parameters on the fly like this: @example emacs -batch -l ~/.emacs \ -eval '(org-batch-agenda "a" \ - org-agenda-span month \ + org-agenda-span (quote month) \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ | lpr @@ -15139,7 +16040,7 @@ The following example counts the number of entries with TODO keyword @uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the @i{iPhone/iPod Touch} series of devices, developed by Richard Moreland. -@i{MobileOrg} offers offline viewing and capture support for an Org-mode +@i{MobileOrg} offers offline viewing and capture support for an Org mode system rooted on a ``real'' computer. It does also allow you to record changes to existing entries. Android users should check out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} @@ -15168,7 +16069,7 @@ in-buffer settings, but it will understand the logistics of TODO state MobileOrg needs to interact with Emacs through a directory on a server. If you are using a public server, you should consider to encrypt the files that are -uploaded to the server. This can be done with Org-mode 7.02 and with +uploaded to the server. This can be done with Org mode 7.02 and with @i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl} installation on your system. To turn on encryption, set a password in @i{MobileOrg} and, on the Emacs side, configure the variable @@ -15191,7 +16092,7 @@ Emacs about it: (setq org-mobile-directory "~/Dropbox/MobileOrg") @end lisp -Org-mode has commands to put files for @i{MobileOrg} into that directory, +Org mode has commands to put files for @i{MobileOrg} into that directory, and to read captured notes from there. @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg @@ -15204,7 +16105,7 @@ can be included by customizing @code{org-mobile-files}. File names will be staged with paths relative to @code{org-directory}, so all files should be inside this directory. The push operation also creates a special Org file @file{agendas.org} with all custom agenda view defined by the -user@footnote{While creating the agendas, Org-mode will force ID properties +user@footnote{While creating the agendas, Org mode will force ID properties on all referenced entries, so that these entries can be uniquely identified if @i{MobileOrg} flags them for further action. If you do not want to get these properties in so many entries, you can set the variable @@ -15305,7 +16206,7 @@ Before I get to this list, a few special mentions are in order: @table @i @item Bastien Guerry Bastien has written a large number of extensions to Org (most of them -integrated into the core by now), including the LaTeX exporter and the plain +integrated into the core by now), including the @LaTeX{} exporter and the plain list parser. His support during the early days, when he basically acted as co-maintainer, was central to the success of this project. Bastien also invented Worg, helped establishing the Web presence of Org, and sponsors @@ -15340,13 +16241,13 @@ know what I am missing here! @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. @item @i{Christophe Bataillon} created the great unicorn logo that we use on the -Org-mode website. +Org mode website. @item @i{Alex Bochannek} provided a patch for rounding timestamps. @item @i{Jan Böcker} wrote @file{org-docview.el}. @item -@i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files. +@i{Brad Bozarth} showed how to pull RSS feed data into Org mode files. @item @i{Tom Breton} wrote @file{org-choose.el}. @item @@ -15522,7 +16423,7 @@ tweaks and features. extension system, added support for mairix, and proposed the mapping API. @item @i{Ulf Stegemann} created the table to translate special symbols to HTML, -LaTeX, UTF-8, Latin-1 and ASCII. +@LaTeX{}, UTF-8, Latin-1 and ASCII. @item @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content with links transformation to Org syntax. @@ -15530,10 +16431,10 @@ with links transformation to Org syntax. @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual chapter about publishing. @item -@i{Jambunathan K} contributed the OpenDocumentText exporter. +@i{Jambunathan K} contributed the @acronym{ODT} exporter. @item -@i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and -enabled source code highlighting in Gnus. +@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and +enabled source code highlighling in Gnus. @item @i{Stefan Vollmar} organized a video-recorded talk at the Max-Planck-Institute for Neurology. He also inspired the creation of a |