diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS new file mode 100644 index 000000000..bf617b0d4 --- /dev/null +++ b/etc/ORG-NEWS @@ -0,0 +1,3232 @@ +ORG NEWS -*- org -*- + +* Version 7.8 + +** Summary + +- Jambunathan's ODT exporter is now part of Org's core. +- Nicolas' new export engine is now part of =contrib/= +- Standard code block keywords +- 10 new committers +- Many bugfixes + +See below for details. + +** New committers who signed the FSF copyright assigment + +Here is the list of new contributors who signed the FSF papers +since Org 7.7 - welcome, and thanks for your contributions! + +- Andreas Leha +- Christian Moe +- Julian Gehring +- Max Mikhanosha +- Michael Brand +- Niels Giessen +- Pieter Praet +- Sergey Litvinov +- Thomas Holst +- Thorsten Jolitz + +** The ODT exporter is now part of Org's core + +- Full refresh of the OpenDocument Text section in the + manual. All new features listed below are fully-documented. +- Associate custom styles on per-file basis using + =#+ODT_STYLES_FILE:= directive. +- Fontify code listings using an enhanced version of + =htmlfontify.el= and generate line numbers natively. +- Embed MathML and OpenDocument formula files. +- Use LaTeX to MathML converter -- say MathToWeb + (http://www.mathtoweb.com/) -- for handling LaTeX Math + fragments. +- In tables, use column width cookies to control relative width + of columns. +- Also for tables, you can specify custom styles using + =#+ATTR_ODT:= lines. +- Lots of bug fixes. + +*Experimental* + +The following features are /experimental/. These features are +specific to the ODT export engine and their implementation and +usage could change considerably in future versions. + +- Support for list tables -- see this [[http://lists.gnu.org/archive/html/emacs-orgmode/2011-09/msg00017.html][message on the list]]. +- Support for annotation blocks -- see this [[http://lists.gnu.org/archive/html/emacs-orgmode/2011-10/msg01251.html][message on the list]]. + +Special thanks to Jambunathan for his work and his patience +through the process of integrating this vital contribution into +Org's core. + +** New export engine by Nicolas + +See the comment sections in org-element.el and in org-export.el +(in =contrib/lisp/=). Also check the experimental LaTeX exporter +using in =EXPERIMENTAL/org-e-latex.el=. + +Check Nicolas' announcement [[http://comments.gmane.org/gmane.emacs.orgmode/49416][on the list]] and hack around! + +Thanks a lot to Nicolas for this great and promising achievement. + +** Incompatible changes + +*** Standardized code block keywords + +Following a round of on-list discussion, many code block synonyms +have been removed. You can safely move forward the following +syntax: + +- call lines are specified with #+call: +- code blocks are named with #+name: +- results are named with #+name:, however results generated by a + code block may still be labeled with #+results:, and tables + named with #+tblname: will be considered to be named results + +The following function may be used to update an existing Org-mode +buffer to the new syntax: + +#+begin_src emacs-lisp + (defun update-org-buffer () + "Update an Org-mode buffer to the new data, code block and call line syntax." + (interactive) + (save-excursion + (flet ((to-re (lst) (concat "^[ \t]*#\\+" (regexp-opt lst t) + "\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:[ \t]*")) + (update (re new) + (goto-char (point-min)) + (while (re-search-forward re nil t) + (replace-match new nil nil nil 1)))) + (let ((old-re (to-re '("RESULTS" "DATA" "SRCNAME" "SOURCE"))) + (lob-re (to-re '("LOB"))) + (case-fold-search t)) + (update old-re "name") + (update lob-re "call"))))) +#+end_src + +*Note*: If an old version of Org-mode (e.g., the one shipped with +Emacs) is installed on your system, many of the important +variables will be pre-defined with a =defvar= and *will not* have +their values automatically updated -- these include the +following: + +- =org-babel-data-names= +- =org-babel-result-regexp= +- =org-babel-src-block-regexp= +- =org-babel-src-name-regexp= +- =org-babel-src-name-w-name-regexp= + +It may be necessary to either remove the source code of older +versions of Org-mode or to explicitly evaluate the ob.el file. + +*** Removed the =#+BABEL:= keyword + +Code block header arguments may now be specified using the +standard =#+Property:= keyword. See [[#accumulating-property-keywords][Property names ending in =+= +accumulate]] for more information on the extended property syntax. + +*** Deleted =org-mode-p= + +This function has been deleted: please update your hacks if you +relied on it. + +** New features and user-visible improvements + +*** Day names are optional when you type timestamps manually + +You can type "<2011-12-12>" or [2011-12-12] and modify this timestamps with +S- like other timestamps. Thanks to Carsten for implementing this. + +*** Improved filtering through =org-agenda-to-appt= + +The new function allows the user to refine the scope of entries +to pass to =org-agenda-get-day-entries= and allows to filter out +entries using a function. + +Thanks to Peter Münster for raising a related issue and to +Tassilo Horn for this idea. Also thanks to Peter Münster for +[[git:68ffb7a7][fixing a small bug]] in the final implementation. + +*** =org-agenda-date-later= jumps to today when modifying past date + +The command =org-agenda-date-later= ( in the Agenda +Mode) directly jumps to today. Thanks to Carsten for +implementing this. + +*** Use prefix arg 0 to inhibit note taking for TODO change + +See Carsten's comment: "Sometimes I want to quickly make a few TODOs done +in the agenda and I want to bypass the note taking I have normally set +up. With this change, I can press `0 t d' in the agenda to do this." + +Thanks to Carsten for implementing this. + +*** Various improvements to =org-indent.el= + +Nicolas Goaziou worked on refactoring and improving +=org-indent.el=, which should now be faster. It also better +combines with =visual-line-mode=. + +*** Property names ending in =+= accumulate + +This results in the following behavior. + +#+begin_src org + ,#+property: var foo=1 + ,#+property: var+ bar=2 + + ,#+begin_src emacs-lisp + , (+ foo bar) + ,#+end_src + + ,#+results: + ,: 3 + + ,#+begin_src emacs-lisp + , (org-entry-get (point) "var" t) + ,#+end_src + + ,#+results: + ,: foo=1 bar=2 + + ,* overwriting a file-wide property + , :PROPERTIES: + , :var: foo=7 + , :END: + + ,#+begin_src emacs-lisp + , foo + ,#+end_src + + ,#+results: + ,: 7 + + ,#+begin_src emacs-lisp + , (org-entry-get (point) "var" t) + ,#+end_src + + ,#+results: + ,: foo=7 + + ,* appending to a file-wide property + , :PROPERTIES: + , :var+: baz=3 + , :END: + + ,#+begin_src emacs-lisp + , (+ foo bar baz) + ,#+end_src + + ,#+results: + ,: 6 + + ,#+begin_src emacs-lisp + , (org-entry-get (point) "var" t) + ,#+end_src + + ,#+results: + ,: foo=1 bar=2 baz=3 +#+end_src + +*** =org-agenda-custom-commands= has a default value + +This option used to be `nil' by default. This now has a default +value, displaying an agenda and all TODOs. See the docstring for +details. Thanks to Carsten for this. + +*** =outline-demote/promote= points to =org-demote/promote-subtree= + +Users who use this outline commands in =outline-mode= will want +them to behave the Org way in Org. Thanks to Michael Brand for +the suggestion. + +*** New escape characters for =org-log-note-headings= + +The option =org-log-note-headings= now supports %d and %D for +inactive and active timestamps. This affect the behavior of the +command =org-store-log-note=. Thanks to John J Foerch for a +patch for this. + +*** New command =org-table-transpose-table-at-point= + +See the docstring. This hack from Juan Pechiar is now part of +Org's core. Thanks to Juan! + +*** Allow recursive edit of minibuffer + +You can now use the command =C-c != (=org-time-stamp-inactive=) +when prompted e.g. for a link name. This is because the central +function =org-completing-read= now support recursive edit. Only +=C-c != is available at the moment, but if you can think of a +useful command to use, please let me know. + +Thanks to Skip Collins for the idea and to Nick Dokos for the +implementation. + +*** Allow dynamic construction of the publishing destination + +Thanks to Kai Tetzlaff for adding this. + +*** Set the capture default time to the prompt time + +In the file+datetree+promt target type, the user is being asked +for a date, where to file an entry. In the template, he can use +the escape placeholders for active and inactive time stamps. So +far, these were filled with todays date. This behavior changed +so that, also at %t and %u, the date to use is the one entered at +the prompt. + +Reported by Erik Hetzner and fixed by Carsten. + +*** =org-agenda-skip-additional-timestamps-same-entry= defaults to `nil' +*** org-sudoku.el -- small sudoku solver + +Carsten wrote org-sudoku.el, a little sudoku solver, which lives +in the contrib/ directory. + +From [[http://permalink.gmane.org/gmane.emacs.orgmode/45474][his message]]: "my daughter got stuck with a couple of SUDOKU +puzzles during the vacation (where wh had no internet +connection), so I hacked a small SUDOKU solver that reads a 9x9 +Org table and solves it as a sudoku puzzle. A little silly, but +maybe fun for someone - I have pushed it into the contrib/lisp +directory." +** Code Block related features and improvements +*** Added [[http://cran.r-project.org/web/packages/tikzDevice/index.html][tikzDevice]] support to ob-R.el +*** Support for Pico Lisp code blocks + +Thanks to Thorsten Jolitz Pico Lisp code blocks are now +supported. See =ob-picolisp.el= for more information. + +*** Extension to the =eval= code block header argument + +The =eval= code block header argument now accepts four (six) +possible values the meaning of which is shown in the table below. + +| never or no | The code block will not be evaluated under any | +| | circumstances. | +| query | Evaluation of the code block will require a query. | +| never-export or no-export | The code block will not be evaluated during export | +| | but may still be called | +| query-export | Evaluation of the code block during export will | +| | require a query. | + +*** Update of intermediate results during code block evaluation + +When set to t, the new =org-babel-update-intermediate= variable +will update in-buffer results for code blocks which are evaluated +in the resolution of a variable reference. This can be used to +ensure that the latest returned results are always shown in +buffer. + +*** Support for Fortran code block is now in the core + +Thanks to Sergey Litvinov for contributing this support. + +*** The =sbe= function allows header argument specification + +If first variable is a string and not a cons cell, then interpret +it as a string of header arguments to be passed to the code +block. + +*** Support for Shen code blocks + +See http://www.shenlanguage.org/ for information on Shen. + +A major mode for shen code blocks is available through the GNU +ELPA. + +** New options and faces + +*** New option =org-export-html-headline-anchor-format= + +Format for anchors in HTML headlines. + +It requires to %s: both will be replaced by the anchor referring +to the headline (e.g. "sec-2"). When set to `nil', don't insert +HTML anchors in headlines. + +This was requested by Alan L Tyree. + +*** New option =org-table-formula-field-format= + +Format for fields which contain the result of a formula. +For example, using \"~%s~\" will display the result within tilde +characters. Beware that modifying the display can prevent the +field from being used in another formula. + +Thanks to Dov Grobgeld for this idea. + +*** New option =org-loop-over-headlines-in-active-region= + +When set to `t', some commands will loop over the active +region. Currently, =org-schedule= and =org-deadline= uses this +option: pressing =C-c C-s= or =C-c C-d= when the region is active +will let you schedule/deadline all the visible headlines in the +region. + +Thanks a lot to David Maus for implementing this. + +*** New option =org-catch-invisible-edits= + +This option makes it possible to check what is the right thing to do before +editing invisible regions. Here are the possible values of this option: + +: +nil Do not check, so just do invisible edits. +: +error Throw an error and do nothing. +: +show Make point visible, and do the requested edit. +: +show-and-error Make point visible, then throw an error and abort the edit. +: +smart Make point visible, and do insertion/deletion if it is +: adjacent to visible text and the change feels predictable. + +See the docstring for more details. + +Thanks to Carsten for implementing this. + +*** New option =org-export-latex-table-caption-above= + +Let the user place a caption above its table in LaTeX. +Thanks to Thomas Dye for a patch to this effect. + +*** New option =org-agenda-follow-indirect= + +By setting `org-agenda-follow-indirect' to a non-nil value, +`org-agenda-follow-mode' will use an indirect buffer to display +only the current item, rather than the whole agenda file in which +it lives. + +Thanks to Dave Abrahams for implementing this. + +*** New option =org-refile-active-region-within-subtree= + +Non-nil means also refile active region within a subtree. + +By default =org-refile= doesn't allow refiling regions if they +don't contain a set of subtrees, but it might be convenient to do +so sometimes: in that case, the first line of the region is +converted to a headline before refiling. + +Thanks to Jeff Horn for raising the issue of refiling a list +item, and to Nicolas Goaziou, Nick Dokos and Suvayu Ali for +discussing them patiently. + +*** New option =org-latex-to-mathml-convert-command= + +This option lets you specify a way to convert LaTeX fragments to +MathML. See also =org-latex-to-mathml-jar-file= and the +docstring of =org-create-math-formula=. + +Thanks to Jambunathan K for implementing this. + +*** New option =org-properties-postprocess-alist= + +See its docstring: + +: Alist of properties and functions to adjust inserted values. +: Elements of this alist must be of the form +: +: ([string] [function]) +: +: where [string] must be a property name and [function] must be a +: lambda expression: this lambda expression must take one argument, +: the value to adjust, and return the new value as a string. +: +: For example, this element will allow the property "Remaining" +: to be updated wrt the relation between the "Effort" property +: and the clock summary: +: +: (("Remaining" +: (lambda(value) +: (let ((clocksum (org-clock-sum-current-item)) +: (effort (org-duration-string-to-minutes +: (org-entry-get (point) "Effort")))) +: (org-minutes-to-hh:mm-string (- effort clocksum)))))) + +This is inspired by a request from Pascal Mattia. + +*** New options =org-habit-today-glyph= and =org-habit-completed-glyph= + +This gives you control over the character used for displaying +today (default is `!') and days on which a task has been +completed (default is `*'). Thanks to John Wiegley for this. + +*** New option =org-bibtex-type-property-name= + +Configurable property name for bibtex entry types. Thanks to +Eric Schulte for this. + +*** New face =org-agenda-filter-tags= + +This face is used for highlighting the tag(s) filter in the +modeline. Thanks to Sébastien Vauban for this idea and its +implementation. + +*** New faces =org-agenda-calendar-event= and =org-agenda-calendar-sexp= + +=org-agenda-calendar-event= is the face used to show events and +appointments in the agenda, and =org-agenda-calendar-sexp= the +one used to show events computed from a S-expression. + +Thanks to Sébastien Vauban for this addition. + +** Important bugfixes + +*** Respect =org-export-with-tags= when exporting a subtree + +Thanks to Suvayu Ali for spotting this problem and fixing it. + +*** Fix XEmacs compatibility issue when creating an indirect buffer + +Thanks to Michael Sperber for this fix. + +** Testing + +*** New test function =org-test-with-temp-text-in-file= + +* Version 7.7 + +** COMMENT Incompatible changes +** New features and user-visible improvements + +*** New command =org-copy-visible= (=C-c C-x v=) + +This command will copy the visible text in the region into the +kill ring. + +Thanks to Florian Beck for this function and to Carsten for +adding it to org.el and documenting it! + +*** New hook =org-ctrl-c-ctrl-c-final-hook= + +This hook will be called when nothing special can be performed by +the busy =C-c C-c= key. Thanks to Paul Sexton for this idea! + +*** Allow relative time when scheduling/adding a deadline + +You can now use relative duration strings like "-2d" or "++3w" +when calling =org-schedule= or =org-deadline=: it will schedule +(or set the deadline for) the item respectively two days before +today and three weeks after the current timestamp, if any. + +You can use this programmatically: =(org-schedule nil "+2d")= +will work on the current entry. + +You can also use this while (bulk-)rescheduling and +(bulk-)resetting the deadline of (several) items from the agenda. + +Thanks to Memnon Anon for a heads up about this! + +*** New functions: =org-todo-yesterday= and =org-agenda-todo-yesterday= + +This is useful when you need to mark things done yesterday. + +Thanks to Max Mikhanosha for this patch. + +*** =org-set-property= defaults to the last interactively modified property + +When setting a property with =C-c C-x p=, it will offered the +last interactively modified property as a default choice. If +this command is called on a property line, the property in this +line will take precedence over the last set property. + +*** Clock: Allow synchronous update of timestamps in CLOCK log + +Using =S-M-= on CLOCK log timestamps will +increase/decrease the two timestamps on this line so that +duration will keep the same. Note that duration can still be +slightly modified in case a timestamp needs some rounding. + +Thanks to Rainer Stengele for this idea. + +*** Clock: New function =org-clock-remove-empty-clock-drawer= + +This function removes empty =CLOCK= drawers and has been added to +=org-clock-out-hook=: when clocking out, if no CLOCK log has been +inserted and the drawer is empty, the drawer will be removed. + +*** Capture: new escape sequence =%F= for templates + +Using =%F= in capture templates will insert the full path of the +file or the directory the capture mechanism was called from +(whereas =%f= only insert the filename.) + +Thanks to Nicolas Goaziou for this change. + +*** Agenda: new variable =org-agenda-bulk-custom-functions= for custom bulk functions + +When using =org-agenda-bulk-action= in agenda view, the user +could already call custom functions by pressing =f= and entering +the function's name. + +This variable lets the user add custom choices and reach them +more quickly. Set the variable to an alist of keys (chars) and +functions, and these keys will be accessible through the +=org-agenda-bulk-action= interface. + +If there is a conflict between custom keys and hardcoded choices, +the latter ones take precedence. + +Thanks to Julien Cubizolles for triggering this idea. + +*** Refile: exclude irrelevant headings + +When refiling from an org-mode buffer, the current heading and +its subheadings will be excluded from the list of possible +targets. + +This only works when =org-refile-use-cache= is =nil= and in +org-mode buffers, not in agenda buffers. + +Thanks to Jason Dunsmore for this idea! + +*** Lists: new variable =org-list-use-circular-motion= + +This variable allows some commands to consider lists as cyclic +structures. For example, when non-nil, moving past the last item +of a list with S-down will bring you back to the first one. + +*** Lists: New variable =org-list-indent-offset= + +This variable helps improving readability of sub-items by +increasing their indentation. E.g., if =org-list-indent-offset= +is set to 2, you may see the following list: + +#+begin_example +- First item + - Sub-item 1 + - Sub-item 2 +- Second item +#+end_example + +*** Table: New flag ";t" to tailor the display of computed durations + +See the new variable =org-table-duration-custom-format= and the +updated example from the manual: + +| Task 1 | Task 2 | Total | +|---------+----------+-------| +| 3:02:20 | -2:07:00 | 0.92 | +#+TBLFM: @2$3=$1+$2;t + +In this example, =0.92= is a fraction of hour, the default for +=org-table-duration-custom-format=. + +Thanks to Daniel E. Doherty for discussions about this. + +*** Table: display field's coordinates when editing it with =C-c `= + +When editing a field with =C-c `=, the field's coordinate will +the displayed in the buffer. + +Thanks to Michael Brand for a patch to this effect. + +*** Babel: support for =java= code blocks + +Evaluation of blocks of Java code is now possible. Currently +only external evaluation of Java code is supported (i.e., no +session evaluation) and only the =:results output= results are +collected. Code blocks are compiled to a Java class file which +are then evaluated and the values printed to STDOUT are returned. + +Java code blocks required a =:classname= header argument which is +used by the compiler to name =.java= and =.class= files. + +Example Java code block: +#+begin_src org + ,#+begin_src java :classname myfirstjavaprog + , class myfirstjavaprog + , { + , public static void main(String args[]) + , { + , System.out.println("Hello World!"); + , } + , } + ,#+end_src + + ,#+results: + ,: Hello World! +#+end_src + +*** Babel: support for =fortran= code blocks by Sergey Litvinov + +The =contrib/babel/langs/= contains the new library +=ob-fortran.el= by Sergey Litvinov. + +Thanks to him for this addition. + +*** Babel: support for the [[http://fomus.sourceforge.net/][fomus]] language by Torsten Anders + +=ob-fomus.el= has been added to =contrib/babel/langs/=. + +Thanks to Torsten Anders for contributing this functionality. + +*** Publish: hide .orgx files and use theindex.org directly + +When :makeindex is `non-nil' in the publishing options, Org will +export an index. It populates the directory with .orgx files: +those files are now hidden (.file.orgx). Also the index is +directly stored in the file =theindex.org=, not in the file +=theindex.inc= (which you can delete). + +Thanks to Nathan Neff and Carsten for pointing at the problems +and solutions. + +*** Export: new variable =org-export-html-divs= to allow custom divs + +The default value of =org-export-html-divs= is =("preamble" +"content" "postamble")= and is used to define the =
= +for the main structure of the exported HTML file. + +Note that modifying the default value will break compatibility +with the =org-info.js= script. + +Also note that the variable =org-export-html-content-div= will +still be checked for compatibility reasons but is not a custom +variable anymore. + +Thanks to Sébastian Vauban for a preliminary version of this +patch. + +*** Export: new variable =org-export-latex-quotes= to customize quotes in LaTeX export + +This allows users to define what quotes they want to use as a +replacement of english double-quotes while exporting to LaTeX. + +In particular, if you use the csquote package, you can configure +Org to output something like \endquote{some quoted text} instead +of "some quoted text". + +Thanks to Frederik for bringing this issue up, and to Thomas S. +Dye, Nick Dokos and Stefan Nobis for elaborating this solution. + +** Important bugfixes + +*** Duration computations now work for complex ranges in tables + +Thanks to Christian Moe for signaling this problem. + +*** Handle recursive setup files correctly + +Thanks to Stefan Vollmar for mentioning this problem. + +** Details + +*** =org-map-entries= can now have 'region as its scope + +Thanks to David Maus for suggesting related improvements to +=org-map-entries=. This one prepares the possibility of letting +some commands to loop over the active region. + +*** org-depend.el: new chain-find-next trigger option + +See the updated docstring of this file. + +Thanks a lot to Max Mikhanosha for this! + +*** Export: new experimental exporter to MoinMoin by Puneeth Chaganti. + +The =EXPERIMENTAL/= directory contains a new file org-mm.el that +allows you to export an Org file to a MoinMoin file. + +Thanks to Puneeth Chaganti for this addition. + +*** Export: new default for =org-export-html-preamble= + +The default value included the title. It now defaults to the +empty string, as the title is hardcoded and included in the +"content" div. Including the title here is necessary to let +=org-info.js= find it and display the page properly. + +*** Export: new variable =org-lparse-use-flashy-warning= defaulting to =nil= + +Flashy and verbose warnings while exporting to ODT have been +disabled. Set this to =t= if you want it back. + +*** Export: new default value for =org-export-latex-image-default-option= + +This used to be =width=10em= and this is now width=.9\linewidth, +which makes more sense. + +Thanks to Sebastien Vauban for this suggestion. + +*** Export: allow =org-export-latex-href-format= to have only one "%s" + +This is useful when you want to use \url{link} instead of the +default \href{link}{path}. + +Thanks to Henri-Paul Indiogine for bringing this up. + +** Known issues + +*** The ODT exporter will choke when using some Org-defined strings + +For example, using the hungarian version of the table of +contents, as defined in =org-export-language-setup=, the ODT +exporter will complain about a problem with the translated +string. + +The workaround is to customize =org-export-language-setup= +and to use accents directly. + +* Version 7.6 + +** Incompatible changes +** New features and user-visible improvements + +*** Integration of Jambunathan's OpenDocumentText Exporter + +**** Activation + +Org-mode 7.6 supports exporting to OpenDocument Text (=odt=) +format using org-odt.el. Depending on how you installed Org, +this module can be enabled in one of the following ways: + +1. If you have downloaded the Org from the Web, either as a + distribution =.zip= or =.tar.gz= file, or as a Git archive, + enable the =odt= option in the variable =org-modules=. + +2. If you are using Org-mode 7.6 that comes bundled with + Emacs-24.0.50 (or future Emacs-24.1), then you can install the + OpenDocumentText exporter using the package manager. Check + the list of available packages with =M-x list-packages= and + install the =org-odt= package. + +Thanks a lot to Jambunathan K for this great contribution. + +**** Keybindings + +The following interactive commands are provided: + +1. =C-c C-e o= (=org-export-as-odt=): Export as an =odt= file. + +2. =C-c C-e O= (=org-export-as-odt-and-open=): Export as an =odt= + file and open the resulting file. + +See the =contrib/odt/README.org= file for further details; you +may check in particular the commands =M-x org-lparse= and =M-x +org-export-convert=. + +*** Ob-Lilypond -- new Babel language to allow score generation + +ob-lilypond - an org-babel language, provided to allow LilyPond +music score generation, complete with optional auditioning via +midi, whilst leveraging the full power of org mode, and literate +programming. See https://github.com/mjago/ob-lilypond for more +documentation. + +Thanks to Martyn Jago for this addition. + +*** Org-Bibtex -- major improvements + +Provides support for managing bibtex bibliographical references +data in headline properties. Each headline corresponds to a +single reference and the relevant bibliographic meta-data is +stored in headline properties, leaving the body of the headline +free to hold notes and comments. Org-bibtex is aware of all +standard bibtex reference types and fields. + +The key new functions are + +- org-bibtex-check :: queries the user to flesh out all required + (and with prefix argument optional) bibtex fields available + for the specific reference =type= of the current headline. + +- org-bibtex-create :: Create a new entry at the given level, + using org-bibtex-check to flesh out the relevant fields. + +- org-bibtex-yank :: Yank a bibtex entry on the kill ring as a + formatted Org-mode headline into the current buffer + +- org-bibtex-export-to-kill-ring :: Export the current headline + to the kill ring as a formatted bibtex entry. + +*** Spreadsheet computation of durations and time values + +If you want to compute time values use the =T= flag, either in +Calc formulas or Elisp formulas: + +| Task 1 | Task 2 | Total | +|--------+--------+---------| +| 35:00 | 35:00 | 1:10:00 | +#+TBLFM: @2$3=$1+$2;T + +Values must be of the form =[HH:]MM:SS=, where hours are +optional. + +Thanks to Martin Halder, Eric Schulte and Carsten for code and +feedback on this. + +*** Links within inlined footnotes. + +It as also possible to have footnotes side-by-side correctly +exported. New variables =org-export-latex-footnote-separator=, +=org-export-html-footnote-separator= and +=org-export-docbook-footnote-separator= are used to separate them +in that case. + +Fontification of footnotes is also more accurate. + +*** New variable =org-export-with-tasks= + +Non-nil means include TODO items for export. + +This may have the following values: + +- t include tasks independent of state. +- todo include only tasks that are not yet done. +- done include only tasks that are already done. +- nil remove all tasks before export +- list of TODO kwds keep only tasks with these keywords + +Thanks to Carsten for implementing this! + +*** New variable =org-export-latex-timestamp-inactive-markup= + +This variable allows the user to define the LaTeX markup for +inactive timestamps. It defaults to the same markup than active +timestamps. Thanks to Eric S Fraga for this patch. + +*** New =org-default= face + +=M-x customize-face RET org-default RET= will let you define the +default face for =org-mode= buffers. + +*** Babel improvements +**** In line code block call syntax +It is now possible to call code blocks from within blocks of +prose. + +The new syntax is exactly analogous to the existing =#+call:= +line syntax, only it may be present embedded in a block of prose +for example =call_double(num=8)= would call the =double= code +block assigning the =num= variable to the value =8=. + +**** Optional variable names in code block calls +Variable names are now optional when passing variables to a code +block reference. Un-named variables will be assigned in order as +shown below. + +: #+source: minus +: #+begin_src emacs-lisp :var a=0 :var b=0 +: (- a b) +: #+end_src +: +: #+call: minus(a=8, b=4) +: +: #+call: minus(8,4) + +**** Sub-tree ID as valid code block variable reference +It is now possible to assign the textual contents of an Org-mode +subtree to a code block variable using the ID of the subtree. +Both custom IDs and Org-mode IDs may be used. For example; + +#+begin_src org + ,#+begin_src sh :var text=foo + , echo "$text"|wc + ,#+end_src + + ,#+results: + ,: 8 58 415 + + ,* example foo + , :PROPERTIES: + , :CUSTOM_ID: foo + , :END: + + ,Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec + ,hendrerit tempor tellus. Donec pretium posuere tellus. Proin quam + ,nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis + ,natoque penatibus et magnis dis parturient montes, nascetur ridiculus + ,mus. Nulla posuere. Donec vitae dolor. Nullam tristique diam non + ,turpis. Cras placerat accumsan nulla. Nullam rutrum. Nam vestibulum + ,accumsan nisl. +#+end_src + +**** =org-babel-tangle-body-hook= for reprocessing code block bodies during tangling +**** =padline= header argument controls newline padding during tangling +**** Maxima code blocks are now supported + +Thanks to Eric Fraga for contributing this support. + +**** =awk= code blocks are now supported +**** Added =xmpfilter= to Ruby code blocks for annotated code output +**** New =noweb-ref= header argument + +This header argument may be used to concatenate the bodies of +many code blocks into a single noweb reference. This brings +Org-mode's tangling functionality in line with traditional noweb +tangling. + +A no web reference like the following + +#+begin_src org + ,#+begin_src sh + , <> + ,#+end_src +#+end_src + +will now expand to include the bodies of all code blocks which +are named =the-ref=, as well as all code blocks which have a +=:noweb-ref= header argument set to the value =the-ref=. + +*** New tests + +The =tests/= directory has been extensively updated. + +** Important bugfixes + +*** Org-exp-blocks --- proper handling of recursively nested blocks + +During export pre-processing org-exp-blocks will now ensure that +all matched blocks contain a proper balanced number of +recursively nested blocks. + +Before this fix nested blocks such as the following would break +during export. + +#+begin_src org + ,#+begin_src org + , ,#+begin_example + , , nested example + , ,#+end_example + ,#+end_src +#+end_src + +*** List handling + +Fix an infinite loop when a list has an end of block string +without the corresponding beginning. + +Auto-filling cannot happen at a location where it would otherwise +insert a new item. + +** Details + +*** Footnotes have gone through some bug-fixing: + +- properly ignore footnotes in comments, +- export calls to previously defined footnotes in LaTeX using + \footnotemark, +- export footnotes before first heading (LaTeX), +- export footnotes when selecting a subtree not holding their + definition (LaTeX). + +*** Many small bug fixes have been applied to list handling + +- fix `org-timer-item', +- fix insertion of a new item with a non-nil `indent-tabs-mode', +- fix use of `fill-region' in an item, +- correct export lists within footnotes and footnotes within lists, +- correctly export lists containing macros, +- don't ignore with-case specification when sorting a list, +- better indentation handling when changing an item to an headline + or the other way, +- fix check-boxes' cookies updating. + +* Version 7.5 + +** Incompatible changes + +*** Code block variable initialized with Emacs Lisp code in tables and lists + +It is no longer possible to assign code block variables using +executable Emacs Lisp statements contained in tables or lists. +As per the following example. +#+tblname: table +| (a b c) | + +#+begin_src perl :var data=table[0,0] + $data +#+end_src + +#+results: +: (a b c) + +Thanks to Vladimir Alexiev for raising this issue. + +*** `org-bbdb-anniversary-format-alist' has changed + +Please check the docstring and update your settings accordingly. +** New features and user-visible improvements + +*** Implement formulas applying to field ranges + +Carsten implemented this field-ranges formulas. + +: A frequently requested feature for tables has been to be able to define +: row formulas in a way similar to column formulas. The patch below allows +: things like +: +: @3= +: @2$2..@5$7= +: @I$2..@II$4= +: +: as the left hand side for table formulas in order to write a formula that +: is valid for an entire column or for a rectangular section in a +: table. + +Thanks a lot to Carsten for this. + +*** Improved handling of lists + +Nicolas Goaziou extended and improved the way Org handles lists. + +1. Indentation of text determines again end of items in + lists. So, some text less indented than the previous item + doesn't close the whole list anymore, only all items more + indented than it. + +2. Alphabetical bullets are implemented, through the use of the + variable `org-alphabetical-lists'. This also adds alphabetical + counters like [@c] or [@W]. + +3. Lists can now safely contain drawers, inline tasks, or various + blocks, themselves containing lists. Two variables are + controlling this: `org-list-forbidden-blocks', and + `org-list-export-context'. + +4. Improve `newline-and-indent' (C-j): used in an item, it will + keep text from moving at column 0. This allows to split text + and make paragraphs and still not break the list. + +5. Improve `org-toggle-item' (C-c -): used on a region with + standard text, it will change the region into one item. With a + prefix argument, it will fallback to the previous behavior and + make every line in region an item. It permits to easily + integrate paragraphs inside a list. + +6. `fill-paragraph' (M-q) now understands lists. It can freely be + used inside items, or on text just after a list, even with no + blank line around, without breaking list structure. + +Thanks a lot to Nicolas for all this! + +*** Modified link escaping + +David Maus worked on `org-link-escape'. See [[http://article.gmane.org/gmane.emacs.orgmode/37888][his message]]: + +: Percent escaping is used in Org mode to escape certain characters +: in links that would either break the parser (e.g. square brackets +: in link target oder description) or are not allowed to appear in +: a particular link type (e.g. non-ascii characters in a http: +: link). +: +: With this change in place Org will apply percent escaping and +: unescaping more consistently especially for non-ascii characters. +: Additionally some of the outstanding bugs or glitches concerning +: percent escaped links are solved. + +Thanks a lot to David for this work. + +*** Simplification of org-export-html-preamble/postamble + +When set to `t', export the preamble/postamble as usual, honoring +the =org-export-email/author/creator-info= variables. + +When set to a formatting string, insert this string. See the +docstring of these variable for details about available +%-sequences. + +You can set =:html-preamble= in publishing project in the same +way: `t' means to honor =:email/creator/author-info=, and a +formatting string will insert a string. + +*** New command `org-agenda-append-agenda' + +You can now use `org-agenda-append-agenda' to dynamically add new +agendas views to the current one. It is particularily useful to +compare multiple small agendas. + +*** Localized clock tables + +Clock tables now support a new new =:lang= parameter, allowing +the user to customize the localization of the table headers. See +the variable =org-clock-clocktable-language-setup= which controls +available translated strings. + +*** New sorting options when publishing projects + +The =:sitemap-sort-file= option now allows sorting the sitemap +file (anti-)alphabetically and (anti-)chronogically. Thanks a +lot to Manuel Giraud for a patch to this effet. + +*** Testing with ERT + +Martyn Jago added new tests to =testing/= - thanks to him! +*** New file in contrib/: org-notmuch.el + +Org is now distributed with =org-notmuch.el=, by Matthieu +Lemerre. See explanations in the header of =org-notmuch.el=: + +: =org-notmuch.el= implements links to notmuch messages and +: "searchs". A search is a query to be performed by notmuch; it is +: the equivalent to folders in other mail clients. Similarly, mails +: are refered to by a query, so both a link can refer to several +: mails. + +*** org-gnus.el now allows link creation from messages + +You can now create links from messages. This is particularily +useful when the user wants to stored messages that he sends, for +later check. Thanks to Ulf Stegemann for the patch. + +** Important bug fixes + +*** Capturing to narrowed buffers + +You can now safely capture entries to narrowed buffers. Thanks a +lot to Memnon Anon for bringing this up. + +*** Better handling of the new `org-agenda-span' variable + +Agendas were a bit confused by the introduction of this variable, +in particular block agendas. This is now fixed. + +Thanks to Julien and Carsten for helping find the right fix for +this issue, and to Michael Brand and Matt Lundin for their +patient testing and reporting. + +*** Security warning: using org-crypt with auto-save + +To prevent Emacs from auto-saving encrypted entries in clear +text, the user should not use auto-save with org-crypt.el. We +now send a warning when users are both using auto-saving and +org-crypt.el. Thanks to Peter Jones for bringing this up. + +** Details + +*** Babel +**** :file argument causes results to be written to file for all languages +:file should be understood as saying "write the result +to and return a link to ". + +This works for all languages. For graphics languages (e.g. ditaa, dot, +gnuplot) there is no change in behavior: "result" in the above is the +graphics, and a link to the image is placed in the org buffer. For +general-purpose languages (e.g. emacs-lisp, python, R, ruby, shell), +the "result" written to file is the normal org-babel result (string, +number, table). + +In order to return a file link from a src block without telling babel +to save any results to that file, use :results and do not +use :file. The code block can of course write arbitrary content to +. + +Some examples: + +Save the output of ls -l as a .csv file (recall that :results value is +the default): + +#+begin_src sh :file dirlisting.csv :sep , + ls -l +#+end_src + +Send the text output of ls -l directly to file: + +#+begin_src sh :results output :file dirlisting.txt + ls -l +#+end_src + +**** R requires :results graphics :file filename when generating graphics +":results graphics" is now required in addition to ":file +filename" in order for graphical output to be sent automatically +to file. If :file is supplied, but not ":results graphics", then +non-graphical, "value" or "output" results are written to file, +depending on which of those options is in effect. +**** Calc code blocks can now accept vectors +For example; + +#+begin_src calc :var y=[1 2 3] + 3 y +#+end_src + +#+results: +: [3, 6, 9] + +Thanks to Eric S. Fraga for raising this issue + +**** Code blocks with empty bodies are now acceptable + +Previously these caused errors on export. Thanks to Martyn Jago +for this patch. + +**** Emacs Lisp variable assignments which don't eval cleanly passed literally + +This makes it possible to easily pass through non-elisp variable +assignments which may initially look like valid elisp. + +**** Unified naming of =c++= functions to =C++= +Thanks to Martyn Jago for this patch. + +**** `org-babel-execute-buffer' and `org-babel-execute-subtree' now eval inline code blocks as well + +**** New :mkdirp header argument creates parent dirs of tangle targets + +**** New ":comments noweb" option for wrapping noweb references in comment links + +This can be useful to allow backward linking from tangle code +files to the original code block holding noweb-expanded content. + +**** Allow detangling of text containing '\'s -- Thanks to Seth Burleigh + +**** =:sep= specifies table separator when opening or writing tabular results + +**** `org-edit-src-content-indentation' can now be a buffer-local variable +*** All export configuration variables can now be buffer-local variables +*** org-complete.el has been renamed to org-pcomplete.el + +In case you were manually loading =org-complete.el= (which is +*not* necessary anyway), please be aware that the name of this +library was changed to =org-pcomplete.el=. + +*** New user options for LaTeX source code export via minted and listings packages + +New variables `org-export-latex-listings-options' and +`org-export-latex-minted-options' allow package options to be +controlled; `org-export-latex-custom-lang-environments' allows +arbitrary configuration on a per-language basis. + +*** Effort durations now support 2d, 2m, etc. + +Effort duration can now be set as 2h (for 2 hours), etc. This +will be converted to minutes automatically when clocking in an +entry with an effort property. See the =org-effort-durations= +variable. + +Thanks a lot to Lawrence Mitchell for this patch. + +*** New option :clock-keep for capture templates + +A capture template with =:clock-keep t= will prevent the refiling +process from clocking out the entry. If =:clock-resume= is also +`t', =:clock-keep= will take precedence and =:clock-resume= will +be ignored. + +So now =:immediate-finish t :clock-in t :clock-keep t= makes +sense: it will capture a new task and clock it. + +*** Misc + +**** New command `org-agenda-bulk-mark-regexp' + +=M-x org-agenda-bulk-mark-regexp RET= will mark agenda entries +which headings match against a regular expression. You can call +this command with the `%' key from an agenda buffer. + +**** New command `org-agenda-reset-view' + +Julien Danjou implemented this: + +: This new command lets you switch to day/week/month/year view. +: +: When switching to day or week view, this setting becomes the default for +: subsequent agenda refreshes. Since month and year views are slow to +: create, they do not become the default. A numeric prefix argument may be +: used to jump directly to a specific day of the year, ISO week, month, or +: year, respectively. For example, `32 d' jumps to February 1st, `9 w' to +: ISO week number 9. When setting day, week, or month view, a year may be +: encoded in the prefix argument as well. For example, `200712 w' will jump +: to week 12 in 2007. If such a year specification has only one or two +: digits, it will be mapped to the interval 1938-2037. `v SPC'' will reset to +: what is set in `org-agenda-span'. + +Thanks a lot to Julien for this. + +**** New options for ignoring past or future items in the global todo list + +This patch gives users greater control over which past or future items +they would like to ignore in the global todo list. By setting +org-agenda-todo-ignore-scheduled to 7, for instance, a user can ignore all +items scheduled 7 or more days in the future. Similarly, by setting +org-agenda-todo-ignore-scheduled to -1, a user can ignore all items that +are truly in the past (unlike the 'past setting, which ignores items +scheduled today). + +See the docstrings of these variables: + +- org-agenda-todo-ignore-deadlines +- org-agenda-todo-ignore-scheduled +- org-agenda-todo-ignore-timestamp + +Thanks a lot to Matt Lundin for implementing this and to Paul +Sexton for the idea. + +**** New variable `org-export-table-remove-empty-lines' + +When set to `nil', don't remove empty tables when exporting +tables. This was requested by Eric S Fraga. + +**** New variable `org-table-fix-formulas-confirm' + +Sometime, editing the structure of a table should not edit the +corresponding formulas. This new variable lets the user decide +whether he wants to confirm formula fixes or not. + +**** New variable `org-export-initial-scope' + +This variable controls the initial scope when exporting with `org-export'. +It can be set to 'buffer or 'subtree. If there is an active region, tell +it when prompting the user for an export command. + +**** Show and use the default refile location + +M-x org-refile RET now shows the default refile location. Thanks to +Tassilo Horn for a patch to this effect. + +**** New variable `org-archive-subtree-add-inherited-tags' + +Non-nil means append inherited tags when archiving a subtree. + +**** New variable `org-export-current-backend' + +This variable is dynamically set by exporters. You can check +against its value anytime in your code to see if you are +exporting to HTML, LaTeX, etc. Possible values are 'html, +'latex, 'ascii, 'docbook. Thanks to Eric Schulte and Dan Davison +for ideas and patches in this area. + +**** New hook `org-clock-before-select-task-hook' + +Hook called in task selection just before prompting the user. + +Thanks to Benjamin Drieu for the patch. + +**** = = emphasis now uses \protectedtexttt +**** Author's email now included in the LaTeX title + +When `org-export-email-info' is non-nil, the LaTeX title will +also include the author's email. Thanks to Lawrence Mitchell for +the patch. + + +**** Update contrib/scripts/ditaa.jar to ditaa v0.9 of 2009-11-24 + +**** New variable `org-mobile-files-exclude-regexp' + +This variable lets you exclude files that you don't want in +org-mobile-files. + +**** New variable `org-confirm-elisp-link-not-regexp' + +Set this to a regexp if you want to skip the confirmation step for +Elisp/Shell code matching this regexp. + +**** New variable `org-attach-store-link-p' + +When set to `t', store link to the attached file, at its original location. + +**** `org-table-use-standard-references' now defaults to 'from + +**** Better `org-agenda-repeating-timestamp-show-all' + +When this is set to a list of TODO keywords, the agenda will only show +occurrences of repeating stamps for these TODO keywords. + +**** New command `org-narrow-to-block' + +This command (`C-x n b') will narrow the buffer to the current block. +* Version 7.4 + +** Incompatible changes + +*** Agenda: rework ndays and span handling + +The variable =org-agenda-ndays= is obsolete - please use +=org-agenda-span= instead. + +Thanks to Julien Danjou for this. + +** Details + +*** Improvements with inline tasks and indentation + +There is now a configurable way on how to export inline tasks. See +the new variable =org-inlinetask-export-templates=. + +Thanks to Nicolas Goaziou for coding these changes. + +*** Agenda: Added a bulk "scattering" command + +=B S= in the agenda buffer will cause tasks to be rescheduled a random +number of days into the future, with 7 as the default. This is useful +if you've got a ton of tasks scheduled for today, you realize you'll +never deal with them all, and you just want them to be distributed +across the next N days. When called with a prefix arg, rescheduling +will avoid weekend days. + +Thanks to John Wiegley for this. + +*** In-buffer completion is now done using John Wiegleys pcomplete.el + +Thanks to John Wiegley for much of this code. + +*** Sending radio tables from org buffers is now allowed + +Org radio tables can no also be sent inside Org buffers. Also, +there is a new hook which get called after a table has been sent. + +Thanks to Seweryn Kokot. + +*** Command names shown in manual + +The reference manual now lists command names for most commands. +Thanks to Andreas Röhler who started this project. + +*** Allow ap/pm times in agenda time grid + +Times in the agenda can now be displayed in am/pm format. See the new +variable =org-agenda-timegrid-use-ampm=. Thanks to C. A. Webber for +a patch to this effect. + +*** Rewriten clock table code + +The entire clocktable code has been rewritten to add more options and +to make hacking time reports easier. + +Thanks to Erwin Vrolijk for a patch introducing clock tables for +quarters. + +*** Babel +**** Add =msosql= engine to sql code blocks +SQL code blocks can now be executed using the =myosql= engine +using the osql command (from MS SQL Server) on Windows systems. + +Thanks to Sébastien Vauban for this contribution. + +**** Python code blocks now accept a =preamble= header argument +This allows specification of coding declarations and library imports +which must take place in the beginning of a file of executed python +code (note this header argument is used during code block evaluation +unlike the =shebang= header argument which is used during tangling). +For example + +#+begin_src org + ,#+begin_src python :preamble # -*- coding: utf-8 -*- :return s + ,s = "é" + ,#+end_src +#+end_src + +Thanks to Vincent Beffara for this idea. + +**** Code block name is shown during evaluation query +When the user is queried about the evaluation of a named code block +the name of the code block is now displayed. + +Thanks to Tom Dye for this suggestion. + +**** Clojure code blocks results insertion +The results of Clojure code blocks have been improved in two ways. +1. lazy sequences are now expanded for insertion into the Org-mode + buffer +2. pretty printing of results is now possible with both "code" and + "data" pretty print formats + +Thanks to Rick Moynihan for suggesting these changes. + +**** Python code blocks now accept a =:return= header argument +This alleviates the need to explicitly insert return statements into +the bode of Python code blocks. This change both +- allows the same python code blocks to be run both in sessions and + externally +- removes the floating =return= statements which violated python + syntax + +Thanks to Darlan Cavalcante for proposing this feature. + +**** =:results wrap= header argument wraps code block results +The new =:results wrap= wraps code blocks results in a custom +environment making it possible to offset their contents during +export. For example + +#+begin_src org + ,#+begin_src emacs-lisp :results wrap + , "code block results" + ,#+end_src + + ,#+results: + ,#+BEGIN_RESULT + ,: code block results + ,#+END_RESULT +#+end_src + +Thanks to Sébastien Vauban for persistently suggesting this enhancement. + +**** Code block error buffer wiped clean between executions +Previously the code block error buffer accumulated errors making it +difficult to distinguish between previous and current errors. This +buffer is now cleaned before every interactive code block evaluation. + +**** Lists now recognized by code blocks +It is now possible for code blocks to both read and write list +contents from and to Org-mode buffers. For example + +#+begin_src org + ,#+results: a-list + ,- babel + ,- and + ,- org-mode + + ,#+source: a-list + ,#+begin_src emacs-lisp :var lst=a-list :results list + , (reverse lst) + ,#+end_src +#+end_src + +**** Calc added as a supported code block language +The Emacs Calc package can be used through =calc= code blocks allowing +both regular arithmetic operations as well as stack based +calculation. For example + +#+begin_src org + ,#+source: calc-stack + ,#+begin_src calc + , 8 + , 1 + , '+ + , 9 + , '* + ,#+end_src + + ,#+results: calc-stack + ,: 81 + + ,#+source: calc-arithmetic + ,#+begin_src calc :var in=calc-stack + , in / 9 + ,#+end_src + + ,#+results: calc-arithmetic + ,: 9 +#+end_src + +**** "org-babel-detangle" propagates change to source code files into code blocks +`org-babel-detangle' can be used to propagate changes to pure source +code files tangled from embedded code blocks in Org-mode files back to +the original code blocks in the Org-mode file. This can be used on +collaborative projects to keep embedded code blocks up to date with +edits made in pure source code files. + +* Version 7.02 + +** Incompatible Changes +*** Code block hashes +Due to changes in the code resolving code block header arguments +hashing of code block results should now re-run a code block when +an argument to the code block has changed. As a result of this +change *all* code blocks with cached results will be re-run after +upgrading to the latest version. + +*** Testing update +Anyone using the org-mode test suite will need to update the jump +repository for test navigation by executing the following from +the root of the org-mode repository. +: git submodule update +Failure to update this repository will cause loading of +org-test.el to throw errors. +** Details +*** Org-babel speed commands +All Org-babel commands (behind the C-c C-v key prefix) are now +available as speed commands when the point is on the first line of a +code block. This uses the existing Org-mode speed key mechanisms. + +Thanks to Jambunathan K for implementation this new feature. + +*** Fontify code in code blocks. + +Source code in code blocks can now be fontified. Please customize the +varable =org-src-fontify-natively=. For very large blocks (several +hundreds of lines) there can be delays in editing such fontified +blocks, in which case C-c ' should be used to bring up a dedicated +edit buffer. + +Thanks to Dan Davison for this. + +*** Language-mode commands are available in the Org-buffer + The most general machinery for doing this is the macro + `org-babel-do-in-edit-buffer'. There is also the convenience + function `org-babel-do-key-sequence-in-edit-buffer' which makes + use of this macro, and is bound to C-c C-v C-x and C-c C-v x. If + there is an active region contained within the code block, then + this is inherited by the edit buffer. Some examples of the sorts + of usage this permits are + +C-c C-v C-x M-; comment region according to language +C-c C-v C-x C-M-\ indent region according to language + +Users can make these more convenient, e.g. + +(defun my/org-comment-dwim (&optional arg) + (interactive "P") + (or (org-babel-do-key-sequence-in-edit-buffer "\M-;") + (comment-dwim arg))) + +(define-key org-mode-map "\M-;" 'my/org-comment-dwim) + +A common instance of this general pattern is built in to Org-mode, +controlled by the variable `org-src-tab-acts-natively': if this +variable is set, then TAB in a code block has the effect that it would +have in the language major mode buffer. + +*** Org-babel commands are available in language-mode edit buffer + Mirroring the language-native commands in Org buffers above, a new + macro `org-src-do-at-code-block' and convenience function + `org-src-do-key-sequence-at-code-block' provide the converse. When + used in a language major-mode edit buffer (i.e. a buffer generated + by C-c '), `org-src-do-key-sequence-at-code-block' executes a key + sequence at the code block in the source Org buffer. The command + bound to the key sequence in the Org-babel key map is executed + remotely with point temporarily at the start of the code block in + the Org buffer. + + The command is not bound to a key by default, to avoid conflicts + with language major mode bindings. To bind it to C-c @ in all + language major modes, you could use + + (add-hook 'org-src-mode-hook + (lambda () (define-key org-src-mode-map "\C-c@" + 'org-src-do-key-sequence-at-code-block))) + + In that case, for example, C-c @ t issued in code edit buffers + would tangle the current Org code block, C-c @ e would execute + the block and C-c @ h would display the other available + Org-babel commands. + +*** Multi-line header arguments to code blocks +Code block header arguments can now span multiple lines using the +new =#+header:= or =#+headers:= lines preceding a code block or +nested in between the name and body of a named code block. +Examples are given below. + +- multi-line header arguments on an un-named code block + : #+headers: :var data1=1 + : #+begin_src emacs-lisp :var data2=2 + : (message "data1:%S, data2:%S" data1 data2) + : #+end_src + : + : #+results: + : : data1:1, data2:2 + +- multi-line header arguments on a named code block + : #+source: named-block + : #+header: :var data=2 + : #+begin_src emacs-lisp + : (message "data:%S" data) + : #+end_src + : + : #+results: named-block + : : data:2 + +*** Unified handling of variable expansion for code blocks +The code used to resolve variable references in code block header +arguments has now been consolidated. This both simplifies the +code base (especially the language-specific files), and ensures +that the arguments to a code block will not be evaluated multiple +times. This change should not be externally visible to the +Org-mode user. +*** Improved Caching +Code block caches now notice if the value of a variable argument +to the code block has changed, if this is the case the cache is +invalidated and the code block is re-run. The following example +can provide intuition for the new behavior. +#+begin_src org :exports code + ,#+srcname: random + ,#+begin_src R :cache yes + ,runif(1) + ,#+end_src + + ,#+results[a2a72cd647ad44515fab62e144796432793d68e1]: random + ,: 0.4659510825295 + + ,#+srcname: caller + ,#+begin_src emacs-lisp :var x=random :cache yes + ,x + ,#+end_src + + ,#+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller + ,: 0.254227238707244 +#+end_src + +*** Added :headers header argument for LaTeX code blocks +This makes it possible to set LaTeX options which must take place in +the document pre-amble for LaTeX code blocks. This header argument +accepts either a single string or a list, e.g. + +#+begin_src org + ,#+begin_src latex :headers \usepackage{lmodern} :file name1.pdf + , latex body + ,#+end_src + + ,#+begin_src latex :headers '("\\usepackage{mathpazo}" "\\usepackage{fullpage}") :file name2.pdf + , latex body + ,#+end_src +#+end_src + +*** New function `org-export-string' +Allows exporting directly from a string to the specified export format. +*** Code block header argument ":noweb tangle" +Only expands <> syntax references when tangling, not during +export (weaving). +*** New function `org-babel-switch-to-session-with-code' +C-c C-v z (`org-babel-switch-to-session-with-code') is a variant of +C-c C-v C-z (`org-babel-switch-to-session'): instead of switching to +the session buffer, it splits the window between (a) the session +buffer and (b) a language major-mode edit buffer for the code block in +question. This can be convenient for using language major mode for +interacting with the session buffer. + +*** Improvements to R sessions + R now uses standard ESS code evaluation machinery in the :results + value case, which avoids unnecessary output to the comint + buffer. In addition, the R command responsible for writing the + result to file is hidden from the user. Finally, the R code edit + buffer generated by C-c ' is automatically linked to the ESS + session if the current code block is using :session. + +*** Temporary file directory +All babel temporary files are now kept in a single sub-directory in +the /tmp directory and are cleaned up when Emacs exits. + +*** Function for demarcating blocks `org-babel-demarcate-block' +Can be called to wrap the region in a block, or to split the block +around point, bound to (C-c C-v d). + +*** Function for marking code block contents `org-babel-mark-block' + Bound to C-M-h in the babel key map (i.e. C-c C-v C-M-h by + default). This can be useful in conjunction with + `org-babel-do-in-edit-buffer', for example for language-native + commenting or indenting of the whole block. +*** Lists of anniversaries are now handeled better + +When several anniversaries are defined in the bbdb anniversaries +field (separated by semicolon), this is now handled nicely by the +agenda. + +Thanks to Łukasz Stelmach for a patch to this effect. + +*** Table fields are now aligned better, new cookie. + +In HTML export, table fields are now properly aligned in accord +with automatic alignment in org, or as set by the ==, ==, and +== cookies. The == cookie is new and has no effect in +Org, but it does do the right thing in HTML export. A LaTeX export +implementation will follow, but is currently still missing. + +*** Update freemind converter to include body text + +The freemind exporter now incorporates body text into the mind +map. + +Thanks to Lennard Borgman for this patch. + +*** Make footnotes work correctly in message-mode +The footnotes code now searches for =message-signature-separator= +(which is "-- " by default) in order to place footnotes before the +signature. Thanks to Tassilo Horn for this patch. + +*** Improve XEmacs compatibility + +Org-mode 7.02 now runs again in 21.4.22 if the new XEmacs base +package is installed. + +Thanks to Uwe Bauer, Volker Ziegler, Michael Sperber and others +for a discussion that lead to this nice result. + +*** Make it configurable wether agenda jumping prefers the future + +When jumping to a date from the agenda using the =j= key, you may +or may not like the property of Org's date reader to prefer the +future when you enter incomplete dates. This can now be +configured using the variable =org-agenda-jump-prefer-future'. + +*** Add publishing functions for ASCII, Latin-1 and UTF-8 + +There are now publishing functions =org-publish-org-to-ascii=, +=org-publish-org-to-latin1=, and =org-publish-org-to-utf8=. + +Thanks to Matthias Danzl for showing how to do this. + +*** Indentation and headline insertion after inline tasks + +Indentation in inline tasks, and headline insertion after inline +tasks now behave as expected. + +*** Encryption in MobileOrg finally works + +As soon as MobilOrg 1.5 hits the Apple's AppStore, you can +encrypt your org files on public servers. Please see the +documentation of MobileOrg and Appendix B of the manual for more +details. + +*** MobileOrg: Do not force to insert IDs + +If you dislike the property of MobileOrg to insert ID properties +for in all entries being part of an agenda view, you can now turn +this off using the variable +=org-mobile-force-id-on-agenda-items=. When this variable is set +to =nil=, MobileOrg will use outline paths to identify entries. +Note that this may fail if several entries have identical outline +paths. + +*** LaTeX minted package for fontified source code export +Patch by Dan Davison. + +A non-nil value of `org-export-latex-minted' means to export source +code using the minted package, which will fontify source code +with color. If you want to use this, you need to make LaTeX use the +minted package. Add minted to `org-export-latex-packages-alist', for +example using customize, or with something like + + (require 'org-latex) + (add-to-list 'org-export-latex-packages-alist '("" "minted")) + +In addition, it is neccessary to install +pygments (http://pygments.org), and to configure +`org-latex-to-pdf-process' so that the -shell-escape option is +passed to pdflatex. + +*** Allow to use texi2dvi or rubber for processing LaTeX to pdf + +Please see the variable =org-export-latex-to-pdf-process= for +more information. + +Thanks to Olivier Schwander for the rubber part. + +*** New STARTUP keywords to turn on inline images + +If you want to inline images whenever you visit an Org file, use + +: #+STARTUP: inlineimages + +*** Support for user-extensible speed commands. + +There is a new hook =org-speed-command-hook=. Thanks to +Jambunathan for a patch to this effect. + +*** Add macro to insert property values into exported text + +you can use {{{property{NAME}}}} to insert the value of a +property upon export. + +Thanks to David Maus for a patch to this effect. + +*** LaTeX package fixes + +We updated the list of default packages loaded by LaTeX exported +files. + +*** Allow "#" and "%" in tags + +Tags can now also contain the characters =#= and =%=, in addition +to =@= and letters. + +*** Show command names in manual + +Andreas Röhler is adding command names to keys in the manual. +This will take a while to complete, but a start has been made. + +*** Make backslash escape "-" in property matches + +When entering a tags/property query, "-" is a logical operator. +However, "-" is also allowed in property names. So you can now +write "SOME\-NAME" to work around this issue. + +This was a request by Ilya Shlyakhter. + +*** Document quick insertion of empty structural elements + +Org-mode has a built-in template mechanism for inserting block +templates. This was undocumented until now. + +Thanks to Jambunathan K for the patch. + +*** Implement MathJax support + +Org-mode now uses MathJax to display math on web pages. We serve +MathJax from the orgmode.org server, at least for the time being +(thanks Bastien!). If you are going to use this for pages which +are viewed often, please install MathJax on your own webserver. + +To return to the old way of creating images and inserting them +into web pages, you would have to set + +: (setq org-export-with-LaTeX-fragments 'dvipng) + +or on a per-file basis + +: #+OPTIONS: LaTeX:dvipng + +*** Agenda: Allow compact two-column display in agenda dispatcher + +If you have many custom agenda commands, you can have the display +in the dispatcher use two columns with the following settings + +: (setq org-agenda-menu-show-match nil +: org-agenda-menu-two-column t) + +This was a request by John Wiegley. + +*** Add org-wikinodes.el as a contributed package + +One frequent request has been to be able to use CamelCase words +for automatic cross links in a Wiki created by Org. THis is now +possible with org-wikinodes.el, which is available in the contrib +directory. We also have some [[http://orgmode.org/worg/org-contrib/org-wikinodes.php][documentation]] for this feature up +on Worg. + +*** Timer/clock enhancements + +=org-timer-set-timer= displays a countdown timer in the modeline. +From the agenda, `J' invokes =org-agenda-clock-goto=. + +* Version 7.01 + +** Incompatible Changes + +*** Emacs 21 support has been dropped + +Do not use Org mode 7.xx with Emacs 21, use [[http://orgmode.org/org-6.36c.zip][version 6.36c]] instead. + +*** XEmacs support requires the XEmacs development version + +To use Org mode 7.xx with XEmacs, you need to run the developer +version of XEmacs. I was about to drop XEmacs support entirely, +but Michael Sperber stepped in and made changes to XEmacs that +made it easier to keep the support. Thanks to Michael for this +last-minute save. I had hoped to be able to remove +xemacs/noutline.el from release 7 by moving it into XEmacs, but +this is not yet done. + +*** Org-babel configuration changes + +Babel took the integration into Org-mode as an opportunity to do +some much needed house cleaning. Most importantly we have +simplified the enabling of language support, and cleared out +unnecessary configuration variables -- which is great unless you +already have a working configuration under the old model. + +The most important changes regard the /location/ and /enabling/ +of Babel (both core functionality and language specific support). + +- Babel :: Babel is now part of the core of Org-mode, so it is + now loaded along with the rest of Org-mode. That means that + there is /no configuration/ required to enable the main + Babel functionality. For current users, this means that + statements like + #+begin_src emacs-lisp + (require 'org-babel) + #+end_src + or + #+begin_src emacs-lisp + (require 'org-babel-init) + #+end_src + that may by lying around in your configuration must now be + removed. +- load path :: Babel (including all language specific files -- + aside from those which are located in the =contrib/= + directory for reasons of licencing) now lives in the base of + the Org-mode lisp directory, so /no additional directories/ + need to be added to your load path to use babel. For Babel + users this means that statements adding babel-specific + directories to your load-path should now be removed from + your config. +- language support :: It is no longer necessary to require + language specific support on a language-by-language basis. + Specific language support should now be managed through the + `org-babel-load-languages' variable. This variable can be + customized using the Emacs customization interface, or + through the addition of something like the following to your + configuration (note: any language not mentioned will /not/ + be enabled, aside from =emacs-lisp= which is enabled by + default) + #+begin_src emacs-lisp + (org-babel-do-load-languages + 'org-babel-load-languages + '((R . t) + (ditaa . t) + (dot . t) + (emacs-lisp . t) + (gnuplot . t) + (haskell . nil) + (ocaml . nil) + (python . t) + (ruby . t) + (screen . nil) + (sh . t) + (sql . nil) + (sqlite . t))) + #+end_src + + Despite this change it is still possible to add + language support through the use of =require= + statements, however to conform to Emacs file-name + regulations all Babel language files have changed + prefix from =org-babel-*= to =ob-*=, so the require + lines must also change e.g. + #+begin_src emacs-lisp + (require 'org-babel-R) + #+end_src + should be changed to + #+begin_src emacs-lisp + (require 'ob-R) + #+end_src + +We have eliminated the =org-babel-tangle-w-comments= variable as +well as the two main internal lists of languages, namely +- =org-babel-interpreters= and +- =org-babel-tangle-langs= + +so any config lines which mention those variables, can/should be +stripped out in their entirety. This includes any calls to the +=org-babel-add-interpreter= function, whose sole purpose was to +add languages to the =org-babel-interpreters= variable. + +With those calls stripped out, we may still in some cases want to +associate a file name extension with certain languages, for +example we want all of our emacs-lisp files to end in a =.el=, we +can do this will the =org-babel-tangle-lang-exts= variable. In +general you shouldn't need to touch this as it already has +defaults for most common languages, and if a language is not +present in org-babel-tangle-langs, then babel will just use the +language name, so for example a file of =c= code will have a =.c= +extension by default, shell-scripts (identified with =sh=) will +have a =.sh= extension etc... + +The configuration of /shebang/ lines now lives in header +arguments. So the shebang for a single file can be set at the +code block level, e.g. + +#+begin_src org + ,#+begin_src clojure :shebang #!/usr/bin/env clj + , (println "with a shebang line, I can be run as a script!") + ,#+end_src +#+end_src + +Note that whenever a file is tangled which includes a /shebang/ +line, Babel will make the file executable, so there is good +reason to only add /shebangs/ at the source-code block level. +However if you're sure that you want all of your code in some +language (say shell scripts) to tangle out with shebang lines, +then you can customize the default header arguments for that +language, e.g. + +#+begin_src emacs-lisp + ;; ensure this variable is defined defined + (unless (boundp 'org-babel-default-header-args:sh) + (setq org-babel-default-header-args:sh '())) + + ;; add a default shebang header argument + (add-to-list 'org-babel-default-header-args:sh + '(:shebang . "#!/bin/bash")) +#+end_src + +The final important change included in this release is the +addition of new security measures into Babel. These measures are +in place to protect users from the accidental or uninformed +execution of code. Along these lines /every/ execution of a code +block will now require an explicit confirmation from the user. +These confirmations can be stifled through customization of the +`org-confirm-babel-evaluate' variable, e.g. +#+begin_src emacs-lisp + ;; I don't want to be prompted on every code block evaluation + (setq org-confirm-babel-evaluate nil) +#+end_src + +In addition, it is now possible to remove code block evaluation +form the =C-c C-c= keybinding. This can be done by setting the +=org-babel-no-eval-on-ctrl-c-ctrl-c= variable to a non-nil value, +e.g. +#+begin_src emacs-lisp + ;; I don't want to execute code blocks with C-c C-c + (setq org-babel-no-eval-on-ctrl-c-ctrl-c t) +#+end_src + +An additional keybinding has been added for code block +evaluation, namely =C-c C-v e=. + +Whew! that seems like a lot of effort for a /simplification/ of +configuration. + +*** New keys for TODO sparse trees + +The key =C-c C-v= is now reserved for Org Babel action. TODO +sparse trees can still be made with =C-c / t= (all not-done +states) and =C-c / T= (specific states). + +*** Customizable variable changes for DocBook exporter + +To make it more flexible for users to provide DocBook exporter +related commands, we start to use format-spec to format the +commands in this release. If you use DocBook exporter and use it +to export Org files to PDF and/or FO format, the settings of the +following two customizable variables need to be changed: + +- =org-export-docbook-xslt-proc-command= +- =org-export-docbook-xsl-fo-proc-command= + +Instead of using =%s= in the format control string for all +arguments, now we use /three/ different format spec characters: + +- =%i=: input file argument +- =%o=: output file argument +- =%s=: XSLT stylesheet argument + +For example, if you set =org-export-docbook-xslt-proc-command= to + +: java com.icl.saxon.StyleSheet -o %s %s /path/to/docbook.xsl + +in the past, now you need to change it to + +: java com.icl.saxon.StyleSheet -o %o %i %s + +and set a new customizable variable called +=org-export-docbook-xslt-stylesheet= to =/path/to/docbook.xsl=. + +Please check the documentation of these two variables for more +details and other examples. + +Along with the introduction of variable +=org-export-docbook-xslt-stylesheet=, we also added a new +in-buffer setting called =#+XSLT:=. You can use this setting to +specify the XSLT stylesheet that you want to use on a per-file +basis. This setting overrides +=org-export-docbook-xslt-stylesheet=. + +** Details + +*** Org Babel is now part of the Org core +See [[#ob-configuration-changes][Org-babel configuration changes]] for instructions on how to +update your babel configuration. + +The most significant result of this change is that Babel now has +documentation! It is part of Org-mode's documentation, see +Chapter 14 [[http://orgmode.org/manual/Working-with-source-code.html#Working-with-source-code][Working With Source Code]]. The Babel keybindings +are now listed in the refcard, and can be viewed from any +Org-mode buffer by pressing =C-c C-v h=. In addition this +integration has included a number of bug fixes, and a significant +amount of internal code cleanup. + +*** The default capture system for Org mode is now called org-capture + +This replaces the earlier system org-remember. The manual only +describes org-capture, but for people who prefer to continue to +use org-remember, we keep a static copy of the former manual +section [[http://orgmode.org/org-remember.pdf][chapter about remember]]. + +The new system has a technically cleaner implementation and more +possibilities for capturing different types of data. See +[[http://thread.gmane.org/gmane.emacs.orgmode/26441/focus%3D26441][Carsten's announcement]] for more details. + +To switch over to the new system: + +1. Run + + : M-x org-capture-import-remember-templates RET + + to get a translated version of your remember templates into the + new variable =org-capture-templates=. This will "mostly" work, + but maybe not for all cases. At least it will give you a good + place to modify your templates. After running this command, + enter the customize buffer for this variable with + + : M-x customize-variable RET org-capture-templates RET + + and convince yourself that everything is OK. Then save the + customization. + +2. Bind the command =org-capture= to a key, similar to what you did + with org-remember: + + : (define-key global-map "\C-cc" 'org-capture) + + If your fingers prefer =C-c r=, you can also use this key once + you have decided to move over completely to the new + implementation. During a test time, there is nothing wrong + with using both system in parallel. + +*** Implement pretty display of entities, sub-, and superscripts. + +The command =C-c C-x \= toggles the display of Org's special +entities like =\alpha= as pretty unicode characters. Also, sub +and superscripts are displayed in a pretty way (raised/lower +display, in a smaller font). If you want to exclude sub- and +superscripts, see the variable +=org-pretty-entities-include-sub-superscripts=. + +Thanks to Eric Schulte and Ulf Stegeman for making this possible. + +*** Help system for finding entities + +The new command =M-x org-entities-help= creates a structured +buffer that lists all entities available in Org. Thanks to Ulf +Stegeman for adding the necessary structure to the internal +entity list. + +*** New module to create Gantt charts + +Christian Egli's /org-taskjuggler.el/ module is now part of Org. +He also wrote a [[http://orgmode.org/worg/org-tutorials/org-taskjuggler.php][tutorial]] for it. + +*** Refile targets can now be cached + +You can turn on caching of refile targets by setting the variable +=org-refile-use-cache=. This should speed up refiling if you +have many eligible targets in many files. If you need to update +the cache because Org misses a newly created entry or still +offers a deleted one, press =C-0 C-c C-w=. + +*** Enhanced functionality of the clock resolver + +Here are the new options for the clock resolver: + +: i/q/C-g Ignore this question; the same as keeping all the idle time. +: +: k/K Keep X minutes of the idle time (default is all). If this +: amount is less than the default, you will be clocked out +: that many minutes after the time that idling began, and then +: clocked back in at the present time. +: g/G Indicate that you \"got back\" X minutes ago. This is quite +: different from 'k': it clocks you out from the beginning of +: the idle period and clock you back in X minutes ago. +: s/S Subtract the idle time from the current clock. This is the +: same as keeping 0 minutes. +: C Cancel the open timer altogether. It will be as though you +: never clocked in. +: j/J Jump to the current clock, to make manual adjustments. + +For all these options, using uppercase makes your final state +to be CLOCKED OUT. Thanks to John Wiegley for making these +changes. + +*** A property value of "nil" now means to unset a property + +This can be useful in particular with property inheritance, if +some upper level has the property, and some grandchild of it +would like to have the default settings (i.e. not overruled by a +property) back. + +Thanks to Robert Goldman and Bernt Hansen for suggesting this +change. + +*** The problem with comment syntax has finally been fixed + +Thanks to Leo who has been on a year-long quest to get this fixed +and finally found the right way to do it. + +*** Make it possible to protect hidden subtrees from being killed by =C-k= + +This was a request by Scott Otterson. +See the new variable =org-ctrl-k-protect-subtree=. + +*** New module org-mac-link-grabber.el + +This module allows to grab links to all kinds of applications on +a mac. It is available in the contrib directory. + +Thanks to Anthony Lander for this contribution. + +*** LaTeX export: Implement table* environment for wide tables + +Thanks to Chris Gray for a patch to this effect. + +*** When cloning entries, remove or renew ID property + +Thanks to David Maus for this change. + +* Version 6.36 + +** Details +*** Inline display of linked images + +Images can now be displayed inline. The key C-c C-x C-v does toggle the +display of such images. Note that only image links that have no +description part will be inlined. + +*** Implement offsets for ordered lists + +If you want to start an ordered plain list with a number different from 1, +you can now do it like this: + +: 1. [@start:12] will star a lit a number 12 + +*** Extensions to storing and opening links to Wanderlust messages + +- Remove filter conditions for messages in a filter folder + + If customization variable `org-wl-link-remove-filter' is non-nil, filter + conditions are stripped of the folder name. + +- Create web links for messages in a Shimbun folder + + If customization variable `org-wl-shimbun-prefer-web-links' is non-nil, + calling `org-store-link' on a Shimbun message creates a web link to the + messages source, indicated in the Xref: header field. + +- Create web links for messages in a nntp folder + + If customization variable `org-wl-nntp-prefer-web-links' is non-nil, + calling `org-store-link' on a nntp message creates a web link either to + gmane.org if the group can be read trough gmane or to googlegroups + otherwise. In both cases the message-id is used as reference. + +- Open links in namazu search folder + + If `org-wl-open' is called with one prefix, WL opens a namazu search + folder for message's message-id using `org-wl-namazu-default-index' as + search index. If this variable is nil or `org-wl-open' is called with + two prefixes Org asks for the search index to use. + +Thanks to David Maus for these changes. + +*** Org-babel: code block body expansion for table and preview + +In org-babel, code is "expanded" prior to evaluation. I.e. the code that is +actually evaluated comprises the code block contents, augmented with the +extra code which assigns the referenced data to variables. It is now +possible to preview expanded contents, and also to expand code during +during tangling. This expansion takes into account all header arguments, +and variables. + +A new key-binding C-c M-b p bound to `org-babel-expand-src-block' can be +used from inside of a source code block to preview its expanded contents +(which can be very useful for debugging). tangling + +The expanded body can now be tangled, this includes variable values which +may be the results of other source-code blocks, or stored in headline +properties or tables. One possible use for this is to allow those using +org-babel for their emacs initialization to store values (e.g. usernames, +passwords, etc…) in headline properties or in tables. + +Org-babel now supports three new header arguments, and new default behavior +for handling horizontal lines in tables (hlines), column names, and +rownames across all languages. + +* Version 6.35 + +** Incompatible Changes + +*** Changes to the intended use of =org-export-latex-classes= + +So far this variable has been used to specify the complete header of the +LaTeX document, including all the =\usepackage= calls necessary for the +document. This setup makes it difficult to maintain the list of packages +that Org itself would like to call, for example for the special symbol +support it needs. Each time I have to add a package, I have to ask people +to revise the configuration of this variable. In this release, I have +tried to fix this. + +First of all, you can *opt out of this change* in the following way: You +can say: /I want to have full control over headers, and I will take +responsibility to include the packages Org needs/. If that is what you +want, add this to your configuration and skip the rest of this section +(except maybe for the description of the =[EXTRA]= place holder): + +#+begin_src emacs-lisp + (setq org-export-latex-default-packages-alist nil + org-export-latex-packages-alist nil) +#+end_src + +/Continue to read here if you want to go along with the modified +setup./ + +There are now two variables that should be used to list the LaTeX +packages that need to be included in all classes. The header +definition in =org-export-latex-classes= should then not contain +the corresponding =\usepackage= calls (see below). + +The two new variables are: + +1. =org-export-latex-default-packages-alist= :: This is the + variable where Org-mode itself puts the packages it needs. + Normally you should not change this variable. The only + reason to change it anyway is when one of these packages + causes a conflict with another package you want to use. + Then you can remove that packages and hope that you are not + using Org-mode functionality that needs it. + +2. =org-export-latex-packages-alist= :: This is the variable + where you can put the packages that you'd like to use across + all classes. For example, I am putting =amsmath= and =tikz= + here, because I always want to have them. + +The sequence how these customizations will show up in the LaTeX +document are: +1. Header from =org-export-latex-classes= +2. =org-export-latex-default-packages-alist= +3. =org-export-latex-packages-alist= +4. Buffer-specific things set with =#+LaTeX_HEADER:= + +If you want more control about which segment is placed where, or +if you want, for a specific class, have full control over the +header and exclude some of the automatic building blocks, you can +put the following macro-like place holders into the header: + +#+begin_example +[DEFAULT-PACKAGES] \usepackage statements for default packages +[NO-DEFAULT-PACKAGES] do not include any of the default packages +[PACKAGES] \usepackage statements for packages +[NO-PACKAGES] do not include the packages +[EXTRA] the stuff from #+LaTeX_HEADER +[NO-EXTRA] do not include #+LaTeX_HEADER stuff +#+end_example + +If you have currently customized =org-export-latex-classes=, you +should revise that customization and remove any package calls that +are covered by =org-export-latex-default-packages-alist=. This +applies to the following packages: + +- inputenc +- fontenc +- fixltx2e +- graphicx +- longtable +- float +- wrapfig +- soul +- t1enc +- textcomp +- marvosym +- wasysym +- latexsym +- amssymb +- hyperref + +If one of these packages creates a conflict with another package +you are using, you can remove it from +=org-export-latex-default-packages-alist=. But then you risk +that some of the advertised export features of Org will not work +properly. + +You can also consider moving packages that you use in all classes +to =org-export-latex-packages-alist=. If necessary, put the +place holders so that the packages get loaded in the right +sequence. As said above, for backward compatibility, if you omit +the place holders, all the variables will dump their content at +the end of the header. + +Damn, this has become more complex than I wanted it to be. I +hope that in practice, this will not be complicated at all. + +*** The constant =org-html-entities= is obsolete + +Its content is now part of the new constant =org-entities=, which +is defined in the file org-entities.el. =org-html-entities= was +an internal variable, but it is possible that some users did +write code using it - this is why I am mentioning it here. + +** Editing Convenience and Appearance + +*** New faces for title, date, author and email address lines. + +The keywords in these lines are now dimmed out, and the title is +displayed in a larger font, and a special font is also used for +author, date, and email information. This is implemented by the +following new faces: + +org-document-title +org-document-info +org-document-info-keyword + +In addition, the variable =org-hidden-keywords= can be used to +make the corresponding keywords disappear. + +Thanks to Dan Davison for this feature. + +*** Simpler way to specify faces for tags and todo keywords + +The variables =org-todo-keyword-faces=, =org-tag-faces=, and +=org-priority-faces= now accept simple color names as +specifications. The colors will be used as either foreground or +background color for the corresponding keyword. See also the +variable =org-faces-easy-properties=, which governs which face +property is affected by this setting. + +This is really a great simplification for setting keyword faces. +The change is based on an idea and patch by Ryan Thompson. + +*** in tables now means fixed width, not maximum width + +Requested by Michael Brand. + +*** Better level cycling function + +=TAB= in an empty headline cycles the level of that headline +through likely states. Ryan Thompson implemented an improved +version of this function, which does not depend upon when exactly +this command is used. Thanks to Ryan for this improvement. + +*** Adaptive filling + +For paragraph text, =org-adaptive-fill-function= did not handle the +base case of regular text which needed to be filled. This is now +fixed. Among other things, it allows email-style ">" comments +to be filled correctly. + +Thanks to Dan Hackney for this patch. + +*** `org-reveal' (=C-c C-r=) also decrypts encrypted entries (org-crypt.el) + +Thanks to Richard Riley for triggering this change. + +*** Better automatic letter selection for TODO keywords + +When all first letters of keywords have been used, Org now assigns +more meaningful characters based on the keywords. + +Thanks to Mikael Fornius for this patch. + +** Export + +*** Much better handling of entities for LaTeX export + +Special entities like =\therefore= and =\alpha= now know if +they need to be in LaTeX math mode and are formatted accordingly. + +Thanks to Ulf Stegemann for the tedious work to make this +possible. + +*** LaTeX export: Set coding system automatically + +The coding system of the LaTeX class will now be set to the value +corresponding to the buffer's file coding system. This happens +if your setup sets up the file to have a line +=\usepackage[AUTO]{inputenc}= (the default setup does this). + +*** New exporters to Latin-1 and UTF-8 + +While Ulf Stegemann was going through the entities list to +improve the LaTeX export, he had the great idea to provide +representations for many of the entities in Latin-1, and for all +of them in UTF-8. This means that we can now export files rich +in special symbols to Latin-1 and to UTF-8 files. These new +exporters can be reached with the commands =C-c C-e n= and =C-c +C-e u=, respectively. + +When there is no representation for a given symbol in the +targeted coding system, you can choose to keep the TeX-macro-like +representation, or to get an "explanatory" representation. For +example, =\simeq= could be represented as "[approx. equal to]". +Please use the variable =org-entities-ascii-explanatory= to state +your preference. + +*** Full label/reference support in HTML, Docbook, and LaTeX backends + +=#+LABEL= definitions for tables and figures are now fully +implemented in the LaTeX, Docbook, and HTML interfaces. +=\ref{xxx}= is expanded to a valid link in all backends. + +*** BEAMER export: Title of the outline frame is now customizable + +The new option =org-outline-frame-title= allows to set the +title for outline frames in Beamer presentations. + +Patch by Łukasz Stelmach. + +*** BEAMER export: fragile frames are better recognized + +A =lstlisting= environment now also triggers the fragile option in +a beamer frame, just like =verbatim= environments do. + +Thanks to Eric Schulte for this patch. + +*** BEAMER export: Protect <...> macro arguments + +Macros for the BEAMER package can have arguments in angular +brackets. These are now protected just like normal arguments. + +Requested by Bill Jackson. + +*** HTML export: Add class to outline containers using property + +The =HTML_CONTAINER_CLASS= property can now be used to add a +class name to the outline container of a node in HTML export. + +*** New option =org-export-email-info= to turn off export of the email address + +Default is actually off now. + +*** Throw an error when creating an image from a LaTeX snippet fails + +This behavior can be configured with the new option variable +=org-format-latex-signal-error=. + +** Index generation + +Org-mode can now produce a 2-level subject index spanning an +entire publishing project. Write index entries in your files as + +#+begin_src org +,* What is org-mode? +#+index: Org-mode +#+index: Definitions!Org-mode +#+end_src + +where the first line will produce an index entry /Org-mode/, +while the second line will create /Definitions/ with a sub-item +/Org-mode/. Three-level entries are not supported. + +To produce the index, set + +#+begin_src emacs-lisp +:makeindex t +#+end_src + +in the project definition in =org-publish-project-alist=. You +may have to force re-export of all files to get the index by +using a =C-u= prefix to the publishing command: + +#+begin_example +C-u M-x org-publish-all +#+end_example + +Whenever an Org file is published in this project, a new file +with the extension "orgx" will be written. It contains the index +entries and corresponding jump target names. When all project +files are published, Org will produce a new file "theindex.inc" +containing the index as a to-level tree. This file can be +included into any project file using + +#+begin_src org + ,#+include: "theindex.inc" +#+end_src + +Org-mode will also create a file "theindex.org" with this include +statement, and you can build a more complex structure (for +example style definitions, top and home links, etc) around this +statement. When this file already exists, it will not be +overwritten by Org. + +Thanks to Stefan Vollmar for initiating and driving this feature. + +*** TODO Still need to do the LaTeX portion + +** MobileOrg + +*** Encrypting stage files for MobileOrg + +Since the use of (often pubic) servers is needed for MobileOrg, +it is now possible to encrypt the files to be staged for +MobileOrg. Version 1.2 of MobileOrg will be needed for this +feature, and Richard Moreland will show instructions on his +website once that is available. Basically, on the Org-side this +will require the following settings: + +#+begin_src emacs-lisp + (setq org-mobile-use-encryption t + org-mobile-encryption-password "My_MobileOrg_Password") +#+end_src + +So the password will be visible in your local setup, but since +the encryption is only for the public server, this seems +acceptable. + +** Agenda + +*** Specify entry types as an option + +Custom Agenda commands can now limit the sets of entry types +considered for this command by binding =org-agenda-entry-types= +temporarily in the options section of the command. This can lead +to significant speedups, because instead of laboriously finding +entries and then rejecting them, a whole search cycle is skipped. +For more information see the new section in +[[http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php#sec-5][Matt Lundin's agenda custom command tutorial]]. + +Thanks to Matt Lundin for this feature. + +*** Speed up multiple calls to org-diary by only doing buffer prep once + +Also a patch by Matt Lundin. + +*** Show and hide deadlines in the agenda + +You can now hide all deadline entries in the agenda by pressing +=!=. + +Thanks to John Wiegley for this feature. + +*** Agenda: Allow to suppress deadline warnings for entries also scheduled + +The the docstring of the variable +=org-agenda-skip-deadline-prewarning-if-scheduled=. + +*** Expand file names in org-agenda-files (external file case) + +If you are using a file to manage the list of agenda files, the +names in this file can now contain environment variables and "~" +to write them more compactly and portable. + +Thanks to Mikael Fornius for a patch to this effect. + +*** Agenda: Allow TODO conditions in the skip functions + +The agenda skip function has now special support for skipping +based on the TODO state. Here are just two examples, see the +manual for more information. + +#+begin_src emacs-lisp +(org-agenda-skip-entry-if 'todo '(\"TODO\" \"WAITING\")) +(org-agenda-skip-entry-if 'nottodo 'done) +#+end_src + +Thanks to Łukasz Stelmach for this patch. + +*** Extracting the time-of-day when adding diary entries + +The time of day can now be extracted from new diary entries made +from the agenda with (for example) =i d=. When +=org-agenda-insert-diary-extract-time= is set, this is done, and +the time is moved into the time stamp. + +Thanks to Stephen Eglen for this feature. + +*** The customization group org-font-lock has been renamed + +The new name is `org-appearance'. + +Thanks to Dan Davison for a patch to this effect. + +*** The TODO list: Allow skipping scheduled or deadlined entries + +Skipping TODO entries in the global TODO list based on whether +they are scheduled or have a deadline can now be controlled in +more detail. Please see the docstrings of +=org-agenda-todo-ignore-scheduled= and +=org-agenda-todo-ignore-deadline=. + +Thanks to Łukasz Stelmach for patches to this effect. + +** Hyperlinks + +*** Make =org-store-link= point to directory in a dired buffer + +When, in a dired buffer, the cursor is not in a line listing a +file, `org-store-link' will store a link to the directory. + +Patch by Stephen Eglen. + +*** Allow regexps in =org-file-apps= to capture link parameters + +The way extension regexps in =org-file-apps= are handled has +changed. Instead of matching against the file name, the regexps +are now matched against the whole link, and you can use grouping +to extract link parameters which you can then use in a command +string to be executed. + +For example, to allow linking to PDF files using the syntax +=file:/doc.pdf::=, you can add the following entry to +org-file-apps: + +#+begin_example +Extension: \.pdf::\([0-9]+\)\' +Command: evince "%s" -p %1 +#+end_example + +Thanks to Jan Böcker for a patch to this effect. + +** Clocking + +*** Show clock overruns in mode line + +When clocking an item with a planned effort, overrunning the +planned time is now made visible in the mode line, for example +using the new face =org-mode-line-clock-overrun=, or by adding an +extra string given by =org-task-overrun-text=. + +Thanks to Richard Riley for a patch to this effect. + +** Tables + +*** Repair the broken support for table.el tables again. + +Tables created with the table.el package now finally work again +in Org-mode. While you cannot edit the table directly in the +buffer, you can use =C-c '= to edit it nicely in a temporary +buffer. + +Export of these tables to HTML seem to work without problems. +Export to LaTeX is imperfect. If fails if the table contains +special characters that will be replaced by the exporter before +formatting the table. The replacement operation changes the +length of some lines, breaking the alignment of the table fields. +Unfortunately this is not easy to fix. It is also not an option +to not do these replacements. The table.el LaTeX exporter will +for example not escape "&" in table fields, causing the exported +tables to be broken. + +** Misc + +*** New logging support for refiling + +Whenever you refile an item, a time stamp and even a note can be +added to this entry. For details, see the new option +=org-log-refile=. + +Thanks to Charles Cave for this idea. + +*** New helper functions in org-table.el + +There are new functions to access and write to a specific table +field. This is for hackers, and maybe for the org-babel people. + +#+begin_example +org-table-get +org-table-put +org-table-current-line +org-table-goto-line +#+end_example + +*** Tables: Field coordinates for formulas, and improved docs + +Calc and Emacs-Lisp formulas for tables can access the current +field coordinates with =@#= and =$#= for row and column, +respectively. These can be useful in some formulas. For +example, to sequentially number the fields in a column, use +~=@#~ as column equation. + +One application is to copy a column from a different table. See +the manual for details. + +Thanks to Michael Brand for this feature. + +*** Archiving: Allow to reverse order in target node + +The new option =org-archive-reversed-order= allows to have +archived entries inserted in a last-on-top fashion in the target +node. + +Requested by Tom. + +*** Better documentation on calc accuracy in tables + +Thanks to Michael Brand for this fix. + +*** Clock reports can now include the running, incomplete clock + +If you have a clock running, and the entry being clocked falls +into the scope when creating a clock table, the time so far spent +can be added to the total. This behavior depends on the setting +of =org-clock-report-include-clocking-task=. The default is +=nil=. + +Thanks to Bernt Hansen for this useful addition. + +*** American-style dates are now understood by =org-read-date= + +So when you are prompted for a date, you can now answer like this + +#+begin_example +2/5/3 --> 2003-02-05 +2/5 --> -02-05 +#+end_example + +*** org-timer.el now allows just one timer + +There is now only a single free timer supported by org-timer.el. +Thanks to Bastien for cleaning this up, after a bug report in +this area by Frédéric Couchet. + +*** Remember: Allow to file as sibling of current clock + +=C-3 C-c C-c= will file the remember entry as a sibling of the +last filed entry. + +Patch by Łukasz Stelmach. + +*** Org-reveal: Double prefix arg shows the entire subtree of the parent + +This can help to get out of an inconsistent state produced for +example by viewing from the agenda. + +This was a request by Matt Lundin. + +*** Add org-secretary.el by Juan Reyero to the contrib directory + +org-secretary.el is a possible setup for group work using +Org-mode. + +Thanks to Juan Reyero for this contribution. + +** Babel + +Eric and Dan have compiled the following list of changes in and +around org-babel. + +- Added support for Matlab and Octave. +- Added support for C and C++ code blocks. +- Added support for the Oz programming language. + Thanks to Torsten Anders for this contribution +- Can now force literal interpretation of table cell contents + with extra "$" in table formula. + Thanks to Maurizio Vitale for this suggestion. +- Variable references which look like lisp forms are now + evaluated. +- No longer adding extension during tangling when filename is + provided. + Thanks to Martin G. Skjæveland and Nicolas Girard for prompting this. +- Added `org-babel-execute-hook' which runs after code block + execution. +- Working directories and remote execution + + This introduces a new header argument :dir. For the duration of + source block execution, default-directory is set to the value + of this header argument. Consequences include: + + - external interpreter processes run in that directory + - new session processes run in that directory (but existing + ones are unaffected) + - relative paths for file output are relative to that directory + + The name of a directory on a remote machine may be specified + with tramp syntax (/user@host:path), in which case the + interpreter executable will be sought in tramp-remote-path, and + if found will execute on the remote machine in the specified + remote directory. +- Tramp syntax can be used to tangle to remote files. + Thanks to Maurizio Vitale and Rémi Vanicat. +- org-R removed from contrib. +- gnuplot can now return it's string output -- when session is + set to "none". +- Now including source code block arguments w/source name on + export. +- Now able to reference file links as results. +- Allow pdf/png generation directly from latex source blocks + with :file header argument. + +* Version 6.34 + +** Incompatible changes + +*** Tags in org-agenda-auto-exclude-function must be lower case. + +When defining an =org-agenda-auto-exclude-function=, you need to +be aware that tag that is being passed into the function is +always lower case - even if it was defined in upper case +originally. + +** Details + +*** Support for creating BEAMER presentations from Org-mode documents + +Org-mode documents or subtrees can now be converted directly in +to BEAMER presentation. Turning a tree into a simple +presentations is straight forward, and there is also quite some +support to make richer presentations as well. See the [[http://orgmode.org/manual/Beamer-class-export.html#Beamer-class-export][BEAMER +section]] in the manual for more details. + +Thanks to everyone who has contributed to the discussion about +BEAMER support and how it should work. This was a great example +for how this community can achieve a much better result than any +individual could. + +*** Hyperlinks + +**** Add Paul Sexton's org-ctags.el + +Targets like =<>= can now be found by Emacs' etag +functionality, and Org-mode links can be used to to link to +etags, also in non-Org-mode files. For details, see the file +/org-ctags.el/. + +This feature uses a new hook =org-open-link-functions= which will +call function to do something special with text links. + +Thanks to Paul Sexton for this contribution. + +**** Add Jan Böcker's org-docview.el + +This new module allows links to various file types using docview, +where Emacs displays images of document pages. Docview link +types can point to a specific page in a document, for example to +page 131 of the Org-mode manual: + +: [[docview:~/.elisp/org/doc/org.pdf::131][Org-Mode Manual]] + +Thanks to Jan Böcker for this contribution. + +**** New link types that force special ways of opening the file + +- =file+sys:/path/to/file= will use the system to open the file, + like double-clicking would. +- file+emacs:/path/to/file will force opening the linked file + with Emacs. + +This was a request by John Wiegley. + +**** Open all links in a node + +When using =C-c C-o= on a headline to get a list of links in the +entry, pressing =RET= will open *all* links. This allows +something like projects to be defined, with a number of files +that have to be opened by different applications. + +This was a request by John Wiegley. + +*** Agenda Views + +**** Improve the logic of the search view. + +The logic of search views is changed a bit. See the docstring of +the function =or-search-view=. + +These changes resulted from a discussion with Matt Lundin. + +**** New face for entries from the Emacs diary + +Entries that enter the Agenda through the Emacs diary now get the +face =org-agenda-diary=. + +This was a request by Thierry Volpiatto. + +**** New function `org-diary-class' to schedule classes with skipped weeks. + +This was a request by Daniel Martins. + +**** Empty matcher means prompt in agenda custom commands + +When an agenda custom command has an empty string as MATCH +element, so far this would lead to a meaningless search using an +empty matcher. Now an empty (or white) string will be +interpreted just like a nil matcher, i.e. the user will be +prompted for the match. + +**** Agenda: Selectively remove some tags from agenda display + +If you use tags very extensively, you might want to exclude some +from being displayed in the agenda, in order to keep the display +compact. See the new option =org-agenda-hide-tags-regexp= for +details. + +This was largely a patch by Martin Pohlack. + +*** Export + +**** Direct export of only the current subtree + +Pressing =1= after =C-c C-e= and before the key that selects the +export backend, only the current subtree will be exported, +exactly as it you had selected it first with =C-c @=. So for +example, =C-c C-e 1 b= will export the current subtree to HTML +and open the result in the browser. + +**** Direct export of enclosing node + +Pressing =SPC= after =C-c C-e= and before the key that selects +the export backend, the enclosing subree that is set up for +subtree export will be exported, exactly as it you had selected +it first with =C-c @=. So for example, =C-c C-e SPC d= will find +the enclosing node with a LaTeX_CLASS property or an +EXPORT_FILE_NAME property and export that. + +**** Caching export images + +Images that are created for example using LaTeX or ditaa for +inclusion into exported files are now cached. This works by +adding a hash to the image name, that reflects the source code +and all relevant settings. So as long as the hash does not +change, the image does not have to be made again. His can lead +to a substantial reduction in export/publishing times. + +Thanks to Eric Schulte for a patch to this effect. + +**** Preserving line breaks for export no longer works + +ASCII export always preserves them - no other export format +does. We had attempted to use =\obeylines= for this in LaTeX, +but that does create too many problems. + +**** New symbols =\EUR= and =\checkmark= + +=\EUR= symbols from Marvosym package, and =\checkmark= are now +supported symbols in Org-mode, i.e. they will be exported +properly to the various backends. + +**** Allow LaTeX_CLASS_OPTIONS to set options, also from a property + +You can set the options to the =\documentclass= command on a +per-file basis, using + +: #+LaTeX_CLASS_OPTIONS: [11pt] + +or on a per-tree basis using the corresponding property. The +defined string will replace the default options entirely. + +**** The encoding of LaTeX files is now handled property + +Org now makes sure that the encoding used by the file created +through the export mechanism is reflected correctly in the + +: \usepackage[CODINGSYSTEM]{inputenc} + +command. So as long as the =org-export-latex-classes= definition +contains an =\usepackage[utf8]{inputenc}= statement, that +statement will be modified so that the correct option is used. + +If you wan to use special encodings, for example =utf8x= instead +of =utf8=, see the variable =org-export-latex-inputenc-alist=. + +This was a request by Francesco Pizzolante. + +*** Property API enhancements + +**** Make a new special property BLOCKED, indicating if entry is blocked + +A new special property BLOCKED returns "t" when the entry is +blocked from switching the TODO state to a DONE state. + +This was a request by John Wiegley. + +**** New hooks for external support for allowed property values + +It is now possible to hook into Org in order to provide the +allowed values for any property with a lisp function. See the +docstring of the variable =org-property-allowed-value-functions= + +**** Allow unrestricted completion on properties + +When listing the allowed values for a property, for example with +a =:name_ALL:= property, completion on these values enforces that +one of the values will be chosen. Now, if you add ":ETC" to the +list of allowed values, it will be interpreted as a switch, and +the completion will be non-restrictive, so you can also choose to +type a new value. + +*** Changes to Org-babel + +- The documentation for Org-babel has been drastically improved + and is available on Worg at + http://orgmode.org/worg/org-contrib/babel/ +- Source-code block names are now exported to HTML and LaTeX +- Org-babel functions are now bound to keys behind a common key + prefix (see + http://orgmode.org/worg/org-contrib/babel/reference.php#sec-5) +- Results are now foldable with TAB +- Header argument values can now be lisp forms +- Readable aliases for #+srcname: and #+resname: +- Sha1 hash based caching of results in buffer +- Can now index into variable values +- org-babel-clojure now supports multiple named sessions + +*** Miscellaneous changes + +**** Make =C-c r C= customize remember templates + +=C-c r C= is now a shortcut for + +: M-x customize-variable RET org-remember-templates RET + +This was a proposal by Adam Spiers. + +**** Use John Gruber's regular expression for URL's + +We now use a better regexp to spot plain links in text. This +regexp is adopted from [[http://daringfireball.net/2009/11/liberal_regex_for_matching_urls][John Gruber's blogpost]]. + +Thanks to William Henney for the pointer. + +**** Implement tag completion of all tags in all agenda files + +The new option =org-complete-tags-always-offer-all-agenda-tags= +makes Org complete all tags from all agenda files if non-nil. +Usually, setting it locally to t in org-remember buffers is the +most useful application of this new feature. + +Thanks to Tassilo Horn for a patch to this effect.