From ab351d442d7bb4d17cbb43638aaed1775d8c0344 Mon Sep 17 00:00:00 2001 From: Rasmus Date: Mon, 18 Sep 2017 12:01:12 +0200 Subject: [PATCH] Update Org to v9.1.1 Please see etc/ORG-NEWS for major changes. --- doc/misc/org.texi | 407 +++---- etc/ORG-NEWS | 493 +++++++++ etc/refcards/orgcard.tex | 2 +- lisp/org/ob-C.el | 31 +- lisp/org/ob-R.el | 4 +- lisp/org/ob-clojure.el | 106 +- lisp/org/ob-core.el | 24 +- lisp/org/ob-exp.el | 23 +- lisp/org/ob-gnuplot.el | 2 +- lisp/org/ob-lilypond.el | 2 +- lisp/org/ob-lua.el | 8 +- lisp/org/ob-maxima.el | 8 +- lisp/org/ob-plantuml.el | 28 +- lisp/org/ob-scheme.el | 156 +-- lisp/org/ob-sql.el | 59 +- lisp/org/ob-sqlite.el | 5 +- lisp/org/ob-tangle.el | 3 +- lisp/org/org-agenda.el | 1378 ++++++++++++------------ lisp/org/org-archive.el | 22 +- lisp/org/org-attach.el | 76 +- lisp/org/org-bbdb.el | 55 +- lisp/org/org-bibtex.el | 13 +- lisp/org/org-capture.el | 398 +++---- lisp/org/org-clock.el | 204 ++-- lisp/org/org-colview.el | 266 +++-- lisp/org/org-compat.el | 335 +++--- lisp/org/org-datetree.el | 53 +- lisp/org/org-element.el | 251 ++--- lisp/org/org-entities.el | 2 + lisp/org/org-gnus.el | 283 ++--- lisp/org/org-habit.el | 2 +- lisp/org/org-info.el | 22 +- lisp/org/org-lint.el | 19 +- lisp/org/org-list.el | 62 +- lisp/org/org-macro.el | 72 +- lisp/org/org-macs.el | 84 ++ lisp/org/org-mouse.el | 23 +- lisp/org/org-protocol.el | 17 +- lisp/org/org-src.el | 29 +- lisp/org/org-table.el | 262 +++-- lisp/org/org-timer.el | 2 +- lisp/org/org-version.el | 4 +- lisp/org/org.el | 2160 +++++++++++++++++--------------------- lisp/org/ox-ascii.el | 11 +- lisp/org/ox-beamer.el | 62 +- lisp/org/ox-html.el | 204 ++-- lisp/org/ox-icalendar.el | 129 ++- lisp/org/ox-latex.el | 91 +- lisp/org/ox-md.el | 119 ++- lisp/org/ox-odt.el | 13 +- lisp/org/ox-org.el | 3 +- lisp/org/ox-publish.el | 664 ++++++------ lisp/org/ox-texinfo.el | 271 ++--- lisp/org/ox.el | 619 +++++++---- 54 files changed, 5366 insertions(+), 4275 deletions(-) diff --git a/doc/misc/org.texi b/doc/misc/org.texi index ca57501f3d8..37f2ba551ae 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -4,8 +4,8 @@ @settitle The Org Manual @include docstyle.texi -@set VERSION 9.0.10 -@set DATE 2017-08-27 +@set VERSION 9.1.1 +@set DATE 2017-09-17 @c Version and Contact Info @set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page} @@ -527,7 +527,6 @@ The built-in agenda views * Weekly/daily agenda:: The calendar page with current tasks * Global TODO list:: All unfinished action items * Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file * Search view:: Find entries by searching for text * Stuck projects:: Find projects you need to review @@ -1311,8 +1310,8 @@ Show the current subtree in an indirect buffer@footnote{The indirect buffer buffer, but will be narrowed to the current tree. Editing the indirect buffer will also change the original buffer, but without affecting visibility in that buffer.}. With a numeric prefix argument N, go up to level N and -then take that tree. If N is negative then go up that many levels. With a -@kbd{C-u} prefix, do not remove the previously used indirect buffer. +then take that tree. If N is negative then go up that many levels. With +a @kbd{C-u} prefix, do not remove the previously used indirect buffer. @orgcmd{C-c C-x v,org-copy-visible} Copy the @i{visible} text in the region into the kill ring. @end table @@ -1422,9 +1421,9 @@ See also the option @code{org-goto-interface}. @cindex subtrees, cut and paste @table @asis -@orgcmd{M-@key{RET},org-insert-heading} +@orgcmd{M-@key{RET},org-meta-return} @vindex org-M-RET-may-split-line -Insert a new heading/item with the same level as the one at point. +Insert a new heading, item or row. If the command is used at the @emph{beginning} of a line, and if there is a heading or a plain list item (@pxref{Plain lists}) at point, the new @@ -2108,16 +2107,14 @@ create the above table, you would only type fields. Even faster would be to type @code{|Name|Phone|Age} followed by @kbd{C-c @key{RET}}. -@vindex org-enable-table-editor @vindex org-table-auto-blank-field -When typing text into a field, Org treats @key{DEL}, -@key{Backspace}, and all character keys in a special way, so that -inserting and deleting avoids shifting other fields. Also, when -typing @emph{immediately after the cursor was moved into a new field -with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the -field is automatically made blank. If this behavior is too -unpredictable for you, configure the options -@code{org-enable-table-editor} and @code{org-table-auto-blank-field}. +When typing text into a field, Org treats @key{DEL}, @key{Backspace}, and all +character keys in a special way, so that inserting and deleting avoids +shifting other fields. Also, when typing @emph{immediately after the cursor +was moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or +@kbd{@key{RET}}}, the field is automatically made blank. If this behavior is +too unpredictable for you, configure the option +@code{org-table-auto-blank-field}. @table @kbd @tsubheading{Creation and conversion} @@ -2672,7 +2669,7 @@ calculation precision is greater. Degree and radian angle modes of Calc. @item @code{F}, @code{S} Fraction and symbolic modes of Calc. -@item @code{T}, @code{t} +@item @code{T}, @code{t}, @code{U} Duration computations in Calc or Lisp, @pxref{Durations and time values}. @item @code{E} If and how to consider empty fields. Without @samp{E} empty fields in range @@ -2789,26 +2786,31 @@ Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}. @cindex Time, computing @vindex org-table-duration-custom-format -If you want to compute time values use the @code{T} flag, either in Calc -formulas or Elisp formulas: +If you want to compute time values use the @code{T}, @code{t}, or @code{U} +flag, either in Calc formulas or Elisp formulas: @example @group | Task 1 | Task 2 | Total | |---------+----------+----------| | 2:12 | 1:47 | 03:59:00 | + | 2:12 | 1:47 | 03:59 | | 3:02:20 | -2:07:00 | 0.92 | - #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;t + #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;U::@@4$3=$1+$2;t @end group @end example Input duration values must be of the form @code{HH:MM[:SS]}, where seconds are optional. With the @code{T} flag, computed durations will be displayed -as @code{HH:MM:SS} (see the first formula above). With the @code{t} flag, -computed durations will be displayed according to the value of the option -@code{org-table-duration-custom-format}, which defaults to @code{'hours} and -will display the result as a fraction of hours (see the second formula in the -example above). +as @code{HH:MM:SS} (see the first formula above). With the @code{U} flag, +seconds will be omitted so that the result will be only @code{HH:MM} (see +second formula above). Zero-padding of the hours field will depend upon the +value of the variable @code{org-table-duration-hour-zero-padding}. + +With the @code{t} flag, computed durations will be displayed according to the +value of the option @code{org-table-duration-custom-format}, which defaults +to @code{'hours} and will display the result as a fraction of hours (see the +third formula in the example above). Negative duration values can be manipulated as well, and integers will be considered as seconds in addition and subtraction. @@ -4034,8 +4036,8 @@ states}), you will be prompted for a TODO keyword through the fast selection interface; this is the default behavior when @code{org-use-fast-todo-selection} is non-@code{nil}. -The same rotation can also be done ``remotely'' from the timeline and agenda -buffers with the @kbd{t} command key (@pxref{Agenda commands}). +The same rotation can also be done ``remotely'' from agenda buffers with the +@kbd{t} command key (@pxref{Agenda commands}). @orgkey{C-u C-c C-t} When TODO keywords have no selection keys, select a specific keyword using @@ -4151,19 +4153,19 @@ be set up like this: @end lisp In this case, different keywords do not indicate a sequence, but rather -different types. So the normal work flow would be to assign a task to a -person, and later to mark it DONE@. Org mode supports this style by adapting -the workings of the command @kbd{C-c C-t}@footnote{This is also true for the -@kbd{t} command in the timeline and agenda buffers.}. When used several -times in succession, it will still cycle through all names, in order to first -select the right type for a task. But when you return to the item after some -time and execute @kbd{C-c C-t} again, it will switch from any name directly -to DONE@. Use prefix arguments or completion to quickly select a specific -name. You can also review the items of a specific TODO type in a sparse tree -by using a numeric prefix to @kbd{C-c / t}. For example, to see all things -Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items -from all agenda files into a single buffer, you would use the numeric prefix -argument as well when creating the global TODO list: @kbd{C-3 C-c a t}. +different types. So the normal work flow would be to assign a task to +a person, and later to mark it DONE@. Org mode supports this style by +adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true +for the @kbd{t} command in the agenda buffers.}. When used several times in +succession, it will still cycle through all names, in order to first select +the right type for a task. But when you return to the item after some time +and execute @kbd{C-c C-t} again, it will switch from any name directly to +DONE@. Use prefix arguments or completion to quickly select a specific name. +You can also review the items of a specific TODO type in a sparse tree by +using a numeric prefix to @kbd{C-c / t}. For example, to see all things Lucy +has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items from all +agenda files into a single buffer, you would use the numeric prefix argument +as well when creating the global TODO list: @kbd{C-3 C-c a t}. @node Multiple sets in one file @subsection Multiple keyword sets in one file @@ -4435,11 +4437,6 @@ lognotedone}.} You will then be prompted for a note, and that note will be stored below the entry with a @samp{Closing Note} heading. -In the timeline (@pxref{Timeline}) and in the agenda -(@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to -display the TODO items with a @samp{CLOSED} timestamp on each day, -giving you an overview of what has been done. - @node Tracking TODO state changes @subsection Tracking TODO state changes @cindex drawer, for state change recording @@ -4654,8 +4651,8 @@ items. Set the priority of the current headline (@command{org-priority}). The command prompts for a priority character @samp{A}, @samp{B} or @samp{C}. When you press @key{SPC} instead, the priority cookie is removed from the -headline. The priorities can also be changed ``remotely'' from the timeline -and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). +headline. The priorities can also be changed ``remotely'' from the agenda +buffer with the @kbd{,} command (@pxref{Agenda commands}). @c @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down} @vindex org-priority-start-cycle-with-default @@ -5901,10 +5898,10 @@ agenda (@pxref{Weekly/daily agenda}). We distinguish: @item Plain timestamp; Event; Appointment @cindex timestamp @cindex appointment -A simple timestamp just assigns a date/time to an item. This is just -like writing down an appointment or event in a paper agenda. In the -timeline and agenda displays, the headline of an entry associated with a -plain timestamp will be shown exactly on that date. +A simple timestamp just assigns a date/time to an item. This is just like +writing down an appointment or event in a paper agenda. In the agenda +display, the headline of an entry associated with a plain timestamp will be +shown exactly on that date. @example * Meet Peter at the movies @@ -6584,9 +6581,8 @@ buffer (see variable @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}. @end table -The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in -the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been -worked on or closed during a day. +The @kbd{l} key may be used the agenda (@pxref{Weekly/daily agenda}) to show +which tasks have been worked on or closed during a day. @strong{Important:} note that both @code{org-clock-out} and @code{org-clock-in-last} can have a global key binding and will not @@ -6649,6 +6645,7 @@ be selected: tree @r{the surrounding level 1 tree} agenda @r{all agenda files} ("file"..) @r{scan these files} + function @r{the list of files returned by a function of no argument} file-with-archives @r{current file and its archives} agenda-with-archives @r{all agenda files, including archives} :block @r{The time block to consider. This block is specified either} @@ -7083,7 +7080,7 @@ would look like: (setq org-capture-templates '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") "* TODO %?\n %i\n %a") - ("j" "Journal" entry (file+datetree "~/org/journal.org") + ("j" "Journal" entry (file+olp+datetree "~/org/journal.org") "* %?\nEntered on %U\n %i\n %a"))) @end group @end smalllisp @@ -7191,21 +7188,19 @@ For non-unique headings, the full path is safer. @item (file+regexp "path/to/file" "regexp to find location") Use a regular expression to position the cursor. -@item (file+datetree "path/to/file") -Will create a heading in a date tree for today's date@footnote{Datetree -headlines for years accept tags, so if you use both @code{* 2013 :noexport:} -and @code{* 2013} in your file, the capture will refile the note to the first -one matched.}. - -@item (file+datetree+prompt "path/to/file") -Will create a heading in a date tree, but will prompt for the date. - -@item (file+weektree "path/to/file") -Will create a heading in a week tree for today's date. Week trees are sorted -by week and not by month unlike datetrees. - -@item (file+weektree+prompt "path/to/file") -Will create a heading in a week tree, but will prompt for the date. +@item (file+olp+datetree "path/to/file" [ "Level 1 heading" ....]) +This target@footnote{Org used to offer four different targets for date/week +tree capture. Now, Org automatically translates these to use +@code{file+olp+datetree}, applying the @code{:time-prompt} and +@code{:tree-type} properties. Please rewrite your date/week-tree targets +using @code{file+olp+datetree} since the older targets are now deprecated.} +will create a heading in a date tree@footnote{A date tree is an outline +structure with years on the highest level, months or ISO-weeks as sublevels +and then dates on the lowest level. Tags are allowed in the tree structure.} +for today's date. If the optional outline path is given, the tree will be +built under the node it is pointing to, instead of at top level. Check out +the @code{:time-prompt} and @code{:tree-type} properties below for additional +options. @item (file+function "path/to/file" function-finding-location) A function to find the right location in the file. @@ -7257,6 +7252,16 @@ with the capture. Note that @code{:clock-keep} has precedence over @code{:clock-resume}. When setting both to @code{t}, the current clock will run and the previous one will not be resumed. +@item :time-prompt +Prompt for a date/time to be used for date/week trees and when filling the +template. Without this property, capture uses the current date and time. +Even if this property has not been set, you can force the same behavior by +calling @code{org-capture} with a @kbd{C-1} prefix argument. + +@item :tree-type +When `week', make a week tree instead of the month tree, i.e. place the +headings for each day under a heading with the current iso week. + @item :unnarrowed Do not narrow the target buffer, simply show the full buffer. Default is to narrow it so that you only see the new material. @@ -7428,6 +7433,9 @@ Note that hard links are not supported on all systems. Attach a file using the copy/move/link method. Note that hard links are not supported on all systems. +@orgcmdtkc{u,C-c C-a u,org-attach-url} +Attach a file from URL + @orgcmdtkc{n,C-c C-a n,org-attach-new} Create a new attachment as an Emacs buffer. @@ -7920,7 +7928,7 @@ important for a particular date, this information must be collected, sorted and displayed in an organized way. Org can select items based on various criteria and display them -in a separate buffer. Seven different view types are provided: +in a separate buffer. Six different view types are provided: @itemize @bullet @item @@ -7933,9 +7941,6 @@ action items, a @emph{match view}, showings headlines based on the tags, properties, and TODO state associated with them, @item -a @emph{timeline view} that shows all events in a single Org file, -in time-sorted view, -@item a @emph{text search view} that shows all entries from multiple files that contain specified keywords, @item @@ -8075,8 +8080,6 @@ Create a list of all TODO items (@pxref{Global TODO list}). @item m @r{/} M Create a list of headlines matching a TAGS expression (@pxref{Matching tags and properties}). -@item L -Create the timeline view for the current buffer (@pxref{Timeline}). @item s Create a list of entries selected by a boolean expression of keywords and/or regular expressions that must or must not occur in the entry. @@ -8130,7 +8133,6 @@ In this section we describe the built-in views. * Weekly/daily agenda:: The calendar page with current tasks * Global TODO list:: All unfinished action items * Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file * Search view:: Find entries by searching for text * Stuck projects:: Find projects you need to review @end menu @@ -8528,26 +8530,6 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or @samp{NEXT}. @end table -@node Timeline -@subsection Timeline for a single file -@cindex timeline, single file -@cindex time-sorted view - -The timeline summarizes all time-stamped items from a single Org mode -file in a @emph{time-sorted view}. The main purpose of this command is -to give an overview over events in a project. - -@table @kbd -@orgcmd{C-c a L,org-timeline} -Show a time-sorted view of the Org file, with all time-stamped items. -When called with a @kbd{C-u} prefix, all unfinished TODO entries -(scheduled or not) are also listed under the current date. -@end table - -@noindent -The commands available in the timeline buffer are listed in -@ref{Agenda commands}. - @node Search view @subsection Search view @cindex search view @@ -9068,7 +9050,7 @@ prefix arguments @kbd{C-u C-u}, show only logging information, nothing else. @c @orgcmdkskc{v [,[,org-agenda-manipulate-query-add} Include inactive timestamps into the current view. Only for weekly/daily -agenda and timeline views. +agenda. @c @orgcmd{v a,org-agenda-archives-mode} @xorgcmd{v A,org-agenda-archives-mode 'files} @@ -9708,8 +9690,9 @@ See the docstring of the variable for more information. If you are away from your computer, it can be very useful to have a printed version of some agenda views to carry around. Org mode can export custom -agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's -@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the +agenda views as plain text, HTML@footnote{You need to install +@file{htmlize.el} from @uref{https://github.com/hniksic/emacs-htmlize,Hrvoje +Niksic's repository.}}, Postscript, PDF@footnote{To create PDF output, the ghostscript @file{ps2pdf} utility must be installed on the system. Selecting a PDF file will also create the postscript file.}, and iCalendar files. If you want to do this only occasionally, use the command @@ -9771,13 +9754,13 @@ or absolute. @end lisp The extension of the file name determines the type of export. If it is -@file{.html}, Org mode will use the @file{htmlize.el} package to convert -the buffer to HTML and save it to this file name. If the extension is -@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce -Postscript output. If the extension is @file{.ics}, iCalendar export is -run export over all files that were used to construct the agenda, and -limit the export to entries listed in the agenda. Any other -extension produces a plain ASCII file. +@file{.html}, Org mode will try to use the @file{htmlize.el} package to +convert the buffer to HTML and save it to this file name. If the extension +is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce +Postscript output. If the extension is @file{.ics}, iCalendar export is run +export over all files that were used to construct the agenda, and limit the +export to entries listed in the agenda. Any other extension produces a plain +ASCII file. The export files are @emph{not} created when you use one of those commands interactively because this might use too much overhead. @@ -10085,7 +10068,7 @@ If the example is source code from a programming language, or any other text that can be marked up by font-lock in Emacs, you can ask for the example to look like the fontified Emacs buffer@footnote{This works automatically for the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package, -which is distributed with Org). Fontified code chunks in @LaTeX{} can be +which you need to install). Fontified code chunks in @LaTeX{} can be achieved using either the @url{https://www.ctan.org/tex-archive/macros/latex/contrib/listings/?lang=en, listings,} or the @@ -10424,7 +10407,7 @@ major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of environments and math templates. Inside Org mode, you can make use of some of the features of CD@LaTeX{} mode. You need to install @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with -AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. +AUC@TeX{}) from @url{https://staff.fnwi.uva.nl/c.dominik/Tools/cdlatex}. Don't use CD@LaTeX{} mode itself under Org mode, but use the light version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all @@ -10624,14 +10607,14 @@ override options set at a more general level. @cindex #+SETUPFILE In-buffer settings may appear anywhere in the file, either directly or -indirectly through a file included using @samp{#+SETUPFILE: filename} syntax. -Option keyword sets tailored to a particular back-end can be inserted from -the export dispatcher (@pxref{The export dispatcher}) using the @code{Insert -template} command by pressing @key{#}. To insert keywords individually, -a good way to make sure the keyword is correct is to type @code{#+} and then -to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-TAB} to -switch windows. Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.} for -completion. +indirectly through a file included using @samp{#+SETUPFILE: filename or URL} +syntax. Option keyword sets tailored to a particular back-end can be +inserted from the export dispatcher (@pxref{The export dispatcher}) using the +@code{Insert template} command by pressing @key{#}. To insert keywords +individually, a good way to make sure the keyword is correct is to type +@code{#+} and then to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept +@kbd{M-TAB} to switch windows. Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} +instead.} for completion. The export keywords available for every back-end, and their equivalent global variables, include: @@ -10690,6 +10673,12 @@ code blocks contained in them. @cindex #+TITLE @cindex document title Org displays this title. For long titles, use multiple @code{#+TITLE} lines. + +@item EXPORT_FILE_NAME +@cindex #+EXPORT_FILE_NAME +The name of the output file to be generated. Otherwise, Org generates the +file name based on the buffer name and the extension based on the back-end +format. @end table The @code{#+OPTIONS} keyword is a compact form. To configure multiple @@ -10862,9 +10851,10 @@ Toggle inclusion of tables (@code{org-export-with-tables}). When exporting sub-trees, special node properties in them can override the above keywords. They are special because they have an @samp{EXPORT_} prefix. -For example, @samp{DATE} and @samp{OPTIONS} keywords become, respectively, -@samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}. Except for @samp{SETUPFILE}, -all other keywords listed above have an @samp{EXPORT_} equivalent. +For example, @samp{DATE} and @samp{EXPORT_FILE_NAME} keywords become, +respectively, @samp{EXPORT_DATE} and @samp{EXPORT_FILE_NAME}. Except for +@samp{SETUPFILE}, all other keywords listed above have an @samp{EXPORT_} +equivalent. @cindex #+BIND @vindex org-export-allow-bind-keywords @@ -10873,11 +10863,6 @@ can become buffer-local during export by using the BIND keyword. Its syntax is @samp{#+BIND: variable value}. This is particularly useful for in-buffer settings that cannot be changed using keywords. -@cindex property, EXPORT_FILE_NAME -Normally Org generates the file name based on the buffer name and the -extension based on the back-end format. For sub-trees, Org can export to a -file name as specified in the @code{EXPORT_FILE_NAME} property. - @node Table of contents @section Table of contents @cindex table of contents @@ -11014,8 +10999,9 @@ Visit the include file at point. @cindex macro replacement, during export @cindex #+MACRO -Macros replace text snippets during export. This is a macro definition in -Org: +@vindex org-export-global-macros +Macros replace text snippets during export. Macros are defined globally in +@code{org-export-global-macros}, or document-wise with the following syntax: @example #+MACRO: name replacement text $1, $2 are arguments @@ -11074,6 +11060,19 @@ This macro refers to the filename of the exported file. This macro returns the value of property @var{PROPERTY-NAME} in the current entry. If @var{SEARCH-OPTION} (@pxref{Search options}) refers to a remote entry, that will be used instead. + +@item @{@{@{n@}@}@} +@itemx @{@{@{n(@var{NAME})@}@}@} +@itemx @{@{@{n(@var{NAME},@var{ACTION})@}@}@} +@cindex n, macro +@cindex counter, macro +This macro implements custom counters by returning the number of times the +macro has been expanded so far while exporting the buffer. You can create +more than one counter using different @var{NAME} values. If @var{ACTION} is +@code{-}, previous value of the counter is held, i.e. the specified counter +is not incremented. If the value is a number, the specified counter is set +to that value. If it is any other non-empty string, the specified counter is +reset to 1. You may leave @var{NAME} empty to reset the default counter. @end table The surrounding brackets can be made invisible by setting @@ -13939,21 +13938,45 @@ This paragraph is preceded by... @node Plain lists in Texinfo export @subsection Plain lists in Texinfo export @cindex #+ATTR_TEXINFO, in plain lists +@cindex Two-column tables, in Texinfo export + +@cindex :table-type attribute, in Texinfo export The Texinfo export back-end by default converts description lists in the Org file using the default command @code{@@table}, which results in a table with two columns. To change this behavior, specify @code{:table-type} with -@code{@@ftable} or @code{@@vtable} attributes. For more information, +@code{ftable} or @code{vtable} attributes. For more information, @inforef{Two-column Tables,,texinfo}. -@vindex org-texinfo-def-table-markup +@vindex org-texinfo-table-default-markup +@cindex :indic attribute, in Texinfo export The Texinfo export back-end by default also applies a text highlight based on -the defaults stored in @code{org-texinfo-def-table-markup}. To override the -default highlight command, specify another one with the @code{:indic} -attribute as shown in this example: +the defaults stored in @code{org-texinfo-table-default-markup}. To override +the default highlight command, specify another one with the @code{:indic} +attribute. + +@cindex Multiple entries in two-column tables, in Texinfo export +@cindex :sep attribute, in Texinfo export +Org syntax is limited to one entry per list item. Nevertheless, the Texinfo +export back-end can split that entry according to any text provided through +the @code{:sep} attribute. Each part then becomes a new entry in the first +column of the table. + +The following example illustrates all the attributes above: @example -#+ATTR_TEXINFO: :indic @@asis -- foo :: This is the text for /foo/, with no highlighting. +#+ATTR_TEXINFO: :table-type vtable :sep , :indic asis +- foo, bar :: This is the common text for variables foo and bar. +@end example + +@noindent +becomes + +@example +@@vtable @@asis +@@item foo +@@itemx bar +This is the common text for variables foo and bar. +@@end table @end example @node Tables in Texinfo export @@ -14011,8 +14034,9 @@ A somewhat obsessive function. @node A Texinfo example @subsection A Texinfo example -Here is a more detailed example Org file. @inforef{GNU Sample -Texts,,texinfo} for an equivalent example using Texinfo code. +Here is a more detailed example Org file. @xref{GNU Sample +Texts,,,texinfo,GNU Texinfo Manual} for an equivalent example using Texinfo +code. @example #+TITLE: GNU Sample @{@{@{version@}@}@} @@ -14140,9 +14164,10 @@ and write it to @code{org-icalendar-combined-agenda-file} file name. @cindex property, SUMMARY @cindex property, DESCRIPTION @cindex property, LOCATION -The iCalendar export back-end includes SUMMARY, DESCRIPTION and LOCATION -properties from the Org entries when exporting. To force the back-end to -inherit the LOCATION property, configure the +@cindex property, TIMEZONE +The iCalendar export back-end includes SUMMARY, DESCRIPTION, LOCATION and +TIMEZONE properties from the Org entries when exporting. To force the +back-end to inherit the LOCATION and TIMEZONE properties, configure the @code{org-use-property-inheritance} variable. When Org entries do not have SUMMARY, DESCRIPTION and LOCATION properties, @@ -14151,6 +14176,12 @@ derives the description from the body of the Org item. The @code{org-icalendar-include-body} variable limits the maximum number of characters of the content are turned into its description. +The TIMEZONE property can be used to specify a per-entry time zone, and will +be applied to any entry with timestamp information. Time zones should be +specified as per the IANA time zone database format, e.g.@: ``Asia/Almaty''. +Alternately, the property value can be ``UTC'', to force UTC time for this +entry only. + Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific applications. @@ -14772,7 +14803,7 @@ however, override everything. @item @code{:texinfo-active-timestamp-format} @tab @code{org-texinfo-active-timestamp-format} @item @code{:texinfo-classes} @tab @code{org-texinfo-classes} @item @code{:texinfo-class} @tab @code{org-texinfo-default-class} -@item @code{:texinfo-def-table-markup} @tab @code{org-texinfo-def-table-markup} +@item @code{:texinfo-table-default-markup} @tab @code{org-texinfo-table-default-markup} @item @code{:texinfo-diary-timestamp-format} @tab @code{org-texinfo-diary-timestamp-format} @item @code{:texinfo-filename} @tab @code{org-texinfo-filename} @item @code{:texinfo-format-drawer-function} @tab @code{org-texinfo-format-drawer-function} @@ -14834,15 +14865,30 @@ becomes @file{sitemap.html}). @item @code{:sitemap-title} @tab Title of sitemap page. Defaults to name of file. +@item @code{:sitemap-format-entry} +@tab With this option one can tell how a site-map entry is formatted in the +site-map. It is a function called with three arguments: the file or +directory name relative to base directory of the project, the site-map style +and the current project. It is expected to return a string. Default value +turns file names into links and use document titles as descriptions. For +specific formatting needs, one can use @code{org-publish-find-date}, +@code{org-publish-find-title} and @code{org-publish-find-property}, to +retrieve additional information about published documents. + @item @code{:sitemap-function} -@tab Plug-in function to use for generation of the sitemap. -Defaults to @code{org-publish-org-sitemap}, which generates a plain list -of links to all files in the project. +@tab Plug-in function to use for generation of the sitemap. It is called +with two arguments: the title of the site-map and a representation of the +files and directories involved in the project as a radio list (@pxref{Radio +lists}). The latter can further be transformed using +@code{org-list-to-generic}, @code{org-list-to-subtree} and alike. Default +value generates a plain list of links to all files in the project. @item @code{:sitemap-sort-folders} @tab Where folders should appear in the sitemap. Set this to @code{first} -(default) or @code{last} to display folders first or last, -respectively. Any other value will mix files and folders. +(default) or @code{last} to display folders first or last, respectively. +When set to @code{ignore}, folders are ignored altogether. Any other value +will mix files and folders. This variable has no effect when site-map style +is @code{tree}. @item @code{:sitemap-sort-files} @tab How the files are sorted in the site map. Set this to @@ -14855,24 +14901,11 @@ a file is retrieved with @code{org-publish-find-date}. @item @code{:sitemap-ignore-case} @tab Should sorting be case-sensitive? Default @code{nil}. -@item @code{:sitemap-file-entry-format} -@tab With this option one can tell how a sitemap's entry is formatted in the -sitemap. This is a format string with some escape sequences: @code{%t} stands -for the title of the file, @code{%a} stands for the author of the file and -@code{%d} stands for the date of the file. The date is retrieved with the -@code{org-publish-find-date} function and formatted with -@code{org-publish-sitemap-date-format}. Default @code{%t}. - @item @code{:sitemap-date-format} @tab Format string for the @code{format-time-string} function that tells how a sitemap entry's date is to be formatted. This property bypasses @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}. -@item @code{:sitemap-sans-extension} -@tab When non-@code{nil}, remove filenames' extensions from the generated sitemap. -Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}). -Defaults to @code{nil}. - @end multitable @node Generating an index @@ -15300,9 +15333,12 @@ Org exports both the code block and the results. Org does not export the code block nor the results. @end table -@vindex org-export-babel-evaluate -To stop Org from evaluating code blocks during export, set -@code{org-export-babel-evaluate} variable to @code{nil}. +@vindex org-export-use-babel +To stop Org from evaluating code blocks to speed exports, use the header +argument @code{:eval never-export} (@pxref{eval}). To stop Org from +evaluating code blocks for greater security, set the +@code{org-export-use-babel} variable to @code{nil}, but understand that +header arguments will have no effect. Turning off evaluation comes in handy when batch processing. For example, markup languages for wikis, which have a high risk of untrusted code. @@ -15312,12 +15348,6 @@ during export, to allow evaluation of just the header arguments but not any code evaluation in the source block, set @code{:eval never-export} (@pxref{eval}). -To evaluate just the inline code blocks, set @code{org-export-babel-evaluate} -to @code{inline-only}. Isolating the option to allow inline evaluations -separate from @samp{src} code block evaluations during exports is not for -security but for avoiding any delays due to recalculations, such as calls to -a remote database. - Org never evaluates code blocks in commented sub-trees when exporting (@pxref{Comment lines}). On the other hand, Org does evaluate code blocks in sub-trees excluded from export (@pxref{Export settings}). @@ -15471,10 +15501,10 @@ For more examples of header arguments for @code{#+CALL:} lines, @cindex code block, library The ``Library of Babel'' is a collection of code blocks. Like a function -library, these code blocks can be called from other Org files. This -collection is in a repository file in Org mode format in the @samp{doc} -directory of Org mode installation. For remote code block evaluation syntax, -@pxref{Evaluating code blocks}. +library, these code blocks can be called from other Org files. A collection +of useful code blocks is available on +@uref{http://orgmode.org/worg/library-of-babel.html,Worg}. For remote code +block evaluation syntax, @pxref{Evaluating code blocks}. @kindex C-c C-v i For any user to add code to the library, first save the code in regular @@ -15511,6 +15541,7 @@ Org supports the following languages for the @samp{src} code blocks: @item Scheme @tab scheme @tab GNU Screen @tab screen @item Sed @tab sed @tab shell @tab sh @item SQL @tab sql @tab SQLite @tab sqlite +@item Vala @tab vala @end multitable Additional documentation for some languages are at @@ -17201,12 +17232,9 @@ The sample script shows batch processing of multiple files using emacs -Q --batch --eval " (progn (require 'ob-tangle) - (mapc (lambda (file) - (save-current-buffer - (find-file file) - (org-babel-tangle) - (kill-buffer))) - command-line-args-left)) + (dolist (file command-line-args-left) + (with-current-buffer (find-file-noselect file) + (org-babel-tangle)))) " "$@@" @end example @@ -17316,6 +17344,7 @@ Org comes with these pre-defined easy templates: @item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE} @item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE} @item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER} +@item @kbd{C} @tab @code{#+BEGIN_COMMENT ... #+END_COMMENT} @item @kbd{l} @tab @code{#+BEGIN_EXPORT latex ... #+END_EXPORT} @item @kbd{L} @tab @code{#+LATEX:} @item @kbd{h} @tab @code{#+BEGIN_EXPORT html ... #+END_EXPORT} @@ -17477,14 +17506,16 @@ have a lower ASCII number than the lowest priority. This line sets a default inheritance value for entries in the current buffer, most useful for specifying the allowed values of a property. @cindex #+SETUPFILE -@item #+SETUPFILE: file -The setup file is for additional in-buffer settings. Org loads this file and -parses it for any settings in it only when Org opens the main file. @kbd{C-c -C-c} on the settings line will also parse and load. Org also parses and -loads the file during normal exporting process. Org parses the contents of -this file as if it was included in the buffer. It can be another Org file. -To visit the file, @kbd{C-c '} while the cursor is on the line with the file -name. +@item #+SETUPFILE: file or URL +The setup file or a URL pointing to such file is for additional in-buffer +settings. Org loads this file and parses it for any settings in it only when +Org opens the main file. If URL is specified, the contents are downloaded +and stored in a temporary file cache. @kbd{C-c C-c} on the settings line +will parse and load the file, and also reset the temporary file cache. Org +also parses and loads the document during normal exporting process. Org +parses the contents of this document as if it was included in the buffer. It +can be another Org file. To visit the file (not a URL), @kbd{C-c '} while +the cursor is on the line with the file name. @item #+STARTUP: @cindex #+STARTUP Startup options Org uses when first visiting a file. @@ -17725,7 +17756,9 @@ If any highlights shown in the buffer from the creation of a sparse tree, or from clock display, remove such highlights. @item If the cursor is in one of the special @code{#+KEYWORD} lines, scan the -buffer for these lines and update the information. +buffer for these lines and update the information. Also reset the Org file +cache used to temporary store the contents of URLs used as values for +keywords like @code{#+SETUPFILE}. @item If the cursor is inside a table, realign the table. The table realigns even if automatic table editor is turned off. @@ -17941,7 +17974,7 @@ Org can use names for constants in formulas in tables. Org can also use calculation suffixes for units, such as @samp{M} for @samp{Mega}. For a standard collection of such constants, install the @file{constants} package. Install version 2.0 of this package, available at -@url{http://www.astro.uva.nl/~dominik/Tools}. Org checks if the function +@url{https://staff.fnwi.uva.nl/c.dominik/Tools/}. Org checks if the function @code{constants-get} has been autoloaded. Installation instructions are in the file, @file{constants.el}. @item @file{cdlatex.el} by Carsten Dominik diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index bb1a4008a7c..d1e476267bf 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -8,6 +8,499 @@ See the end of the file for license conditions. Please send Org bug reports to mailto:emacs-orgmode@gnu.org. +* Version 9.1 + +** Incompatible changes + +*** Variables relative to clocksum duration are obsolete + +~org-time-clocksum-format~, ~org-time-clocksum-use-fractional~ and +~org-time-clocksum-fractional-format~ are obsolete. If you changed +them, consider modifying ~org-duration-format~ instead. + +Variable ~org-time-clocksum-use-effort-durations~ is also obsolete. +Consider setting ~org-duration-units~ instead. + +*** ~org-at-timestamp-p~ optional argument accepts different values + +See docstrings for the allowed values. For backward compatibility, +~(org-at-timestamp-p t)~ is still supported, but should be updated +accordingly. + +*** ~org-capture-templates~ no longer accepts S-expressions as file names + +Since functions are allowed there, a straightforward way to migrate +is to turn, e.g., + +: (file (sexp)) + +into + +: (file (lambda () (sexp))) + +*** Deleted contributed packages + +=org-ebib.el, =org-bullets.el= and =org-mime.el= have been deleted +from the contrib/ directory. + +You can now find them here : + +- https://github.com/joostkremers/ebib +- https://github.com/sabof/org-bullets +- https://github.com/org-mime/org-mime + +*** Change ~org-texinfo-classes~ value +The value cannot support functions to create sectionning commands +anymore. Also, the sectionning commands should include commands for +appendices. See the docstring for more information. +*** Removal of ~:sitemap-sans-extension~ + +The publishing property is no longer recognized, as a consequence of +changes to site-map generation. + +You can get the same functionality by setting ~:sitemap-format-entry~ +to the following + +#+BEGIN_SRC elisp +(lambda (entry style project) + (cond ((not (directory-name-p entry)) + (format "[[file:%s][%s]]" + (file-name-sans-extension entry) + (org-publish-find-title entry project))) + ((eq style 'tree) (file-name-nondirectory (directory-file-name entry))) + (t entry))) +#+END_SRC + +*** Change signature for ~:sitemap-function~ + +~:sitemap-function~ now expects to be called with two arguments. See +~org-publish-project-alist~ for details. + +*** Change signature for some properties in ~org-list-to-generic~ + +~:istart~, ~:icount~, ~:iend~ and ~:isep~ now expect the type of the +list as their first argument. + +*** Change signature for ~org-get-repeater~ +The optional argument is now a string to extract the repeater from. +See docstring for details. + +*** Change signature for ~org-time-string-to-time~ +See docstring for changes. + +*** Change order of items in ~org-agenda-time-grid~ +~org-agenda-time-grid~ gained an extra item to allow users to customize +the string displayed after times in the agenda. See docstring for +details. + +*** ~tags-todo~ custom searches now include DONE keywords + +Use "/!" markup when filtering TODO keywords to get only not-done TODO +keywords. + +*** ~org-split-string~ returns ~("")~ when called on an empty string +It used to return nil. +*** Removal of =ob-scala.el= + +See [[https://github.com/ensime/emacs-scala-mode/issues/114][this github issue]]. + +You can use =ob-scala.el= as packaged in scala-mode, available from the +MELPA repository. + +** New features +*** iCalendar export uses inheritance for TIMEZONE and LOCATION properties +Both these properties can be inherited during iCalendar export, +depending on the value of ~org-use-property-inheritance~. +*** iCalendar export respects a TIMEZONE property +Set the TIMEZONE property on an entry to specify a time zone for that +entry only during iCalendar export. The property value should be +specified as in "Europe/London". +*** ~org-attach~ can move directory contents +When setting a new directory for an entry, org-attach offers to move +files over from the old directory. Using a prefix arg will reset the +directory to old, ID based one. +*** New Org duration library +This new library implements tools to read and print time durations in +various formats (e.g., "H:MM", or "1d 2h 3min"...). + +See ~org-duration-to-minutes~ and ~org-duration-from-minutes~ +docstrings. + +*** Agenda +**** New variable : ~org-agenda-show-future-repeats~ +**** New variable : ~org-agenda-prefer-last-repeat~ +**** New variable : ~org-deadline-past-days~ +See docstring for details. +**** Binding C-c C-x < for ~org-agenda-set-restriction-lock-from-agenda~ +**** New auto-align default setting for =org-agenda-tags-column= + +=org-agenda-tags-column= can now be set to =auto=, which will +automatically align tags to the right edge of the window. This is now +the default setting. + +*** New value for ~org-publish-sitemap-sort-folders~ + +The new ~ignore~ value effectively allows toggling inclusion of +directories in published site-maps. + +*** Babel + +**** Scheme: support for tables +**** Scheme: new variable: ~org-babel-scheme-null-to~ + +This new custom option allows to use a empty list or null symbol to +format the table output, initially assigned to ~hlines~. + +**** Scheme: new header ~:prologue~ + +A new block code header has been created for Org Babel that enables +developers to prepend code to the scheme block being processed. + +Multiple ~:prologue~ headers can be added each of them using a string +with the content to be added. + +The scheme blocks are prepared by surronding the code in the block +with a let form. The content of the ~:prologue~ headers are prepended +before this let form. + +**** Support for hledger accounting reports added +**** Clojure: new setting ~org-babel-clojure-sync-nrepl-timeout~ + +Creation of a new setting to specify the Cider timeout. By setting +the =org-babel-clojure-sync-nrepl-timeout= setting option. The value +is in seconds and if set to =nil= then no timeout will occur. +**** Clojure: new header ~:show-process~ + +A new block code header has been created for Org Babel that enables +developers to output the process of an ongoing process into a new +window/buffer. + +You can tell Org Babel to output the process of a running code block. + +To show that output you only have to specify the =:show-process= +option in the code block's header like this: + +#+begin_example +,#+BEGIN_SRC clojure :results output :show-process t + (dotimes [n 10] + (println n ".") + (Thread/sleep 500)) +,#+END_SRC +#+end_example + +If =:show-process= is specified that way, then when you will run the +code using =C-c C-c= a new window will open in Emacs. Everything that +is output by the REPL will immediately be added to that new window. + +When the processing of the code is finished, then the window and its +buffer will be closed and the results will be reported in the +=#+RESULTS= section. + +Note that the =:results= parameter's behavior is *not* changed. If +=silent= is specified, then no result will be displayed. If =output= +is specified then all the output from the window will appears in the +results section. If =value= is specified, then only the last returned +value of the code will be displayed in the results section. + +**** Maxima: new headers ~:prologue~ and ~:epilogue~ +Babel options ~:prologue~ and ~:epilogue~ have been implemented for +Maxima src blocks which prepend and append, respectively, the given +code strings. This can be useful for specifying formatting settings +which would add clutter to exported code. For instance, you can use +this ~:prologue "fpprintprec: 2; linel: 50;"~ for presenting Maxima +results in a beamer presentation. +**** PlantUML: add support for header arguments + +[[http://plantuml.com/][Plantuml]] source blocks now support the [[http://orgmode.org/manual/prologue.html#prologue][~:prologue~]], [[http://orgmode.org/manual/epilogue.html#epilogue][~:epilogue~]] and +[[http://orgmode.org/manual/var.html#var][~:var~]] header arguments. + +**** SQL: new engine added ~sqsh~ + +A new engine was added to support ~sqsh~ command line utility for use +against Microsoft SQL Server or Sybase SQL server. + +More information on ~sqsh~ can be found here: [[https://sourceforge.net/projects/sqsh/][sourceforge/sqsh]] + +To use ~sqsh~ in an *sql* =SRC_BLK= set the =:engine= like this: + +#+begin_example +,#+BEGIN_SRC sql :engine sqsh :dbhost my_host :dbuser master :dbpassword pass :database support +Select * From Users +Where clue > 0 +,#+END_SRC +#+end_example + +**** SQL: new engine added =vertica= + +A new engine was added to support vsql command line utility for use +against HP Vertica. + +More information on =vsql= can be found here: [[https://my.vertica.com/docs/7.2.x/HTML/index.htm#Authoring/ConnectingToHPVertica/vsql/UsingVsql.htm][my.vertica.com]] + +To use =vertica= in an sql =SRC_BLK= set the =:engine= like this: + +#+BEGIN_EXAMPLE + ,#+BEGIN_SRC sql :engine vertica :dbhost my_host :dbuser dbadmin :dbpassword pw :database vmart + SELECT * FROM nodes; + ,#+END_SRC +#+END_EXAMPLE +**** C++: New header ~:namespaces~ + +The new ~:namespaces~ export option can be used to specify namespaces +to be used within a C++ org source block. Its usage is similar to +~:includes~, in that it can accept multiple, space-separated +namespaces to use. This header is equivalent to adding ~using +namespace ;~ in the source block. Here is a "Hello World" in C++ +using ~:namespaces~: + +#+begin_example + ,#+BEGIN_SRC C++ :results output :namespaces std :includes + cout << "Hello World" << endl; + ,#+END_SRC +#+end_example + +**** Support for Vala language + +[[https://wiki.gnome.org/Projects/Vala][Vala]] language blocks support two special header arguments: + +- ~:flags~ passes arguments to the compiler +- ~:cmdline~ passes commandline arguments to the generated executable + +Support for [[http://orgmode.org/manual/var.html#var][~:var~]] does not exist yet, also there is no [[http://orgmode.org/manual/session.html#session][~:session~]] +support because Vala is a compiled language. + +The Vala compiler binary can be changed via the ~defcustom~ +~org-babel-vala-compiler~. + +*** New ~function~ scope argument for the Clock Table +Added a nullary function that returns a list of files as a possible +argument for the scope of the clock table. +*** Export +**** Implement vernacular table of contents in Markdown exporter +Global table of contents are generated using vanilla Markdown syntax +instead of HTML. Also #+TOC keyword, including local table of +contents, are now supported. +**** Add Slovanian translations +**** Implement ~org-export-insert-image-links~ +This new function is meant to be used in back-ends supporting images +as descriptions of links, a.k.a. image links. See its docstring for +details. +**** New macro : ~{{{n}}}~ +This macro creates and increment multiple counters in a document. See +manual for details. +**** Add global macros through ~org-export-global-macros~ +With this variable, one can define macros available for all documents. +**** New keyword ~#+EXPORT_FILE_NAME~ +Similarly to ~:EXPORT_FILE_NAME:~ property, this keyword allows the +user to specify the name of the output file upon exporting the +document. This also has an effect on publishing. +**** Horizontal rules are no longer ignored in LaTeX table math mode +**** Use ~compilation-mode~ for compilation output +**** Plain lists accept a new ~:separator~ attribute in Texinfo + +The new ~:separator~ attribute splits a tag from a description list +item into multiple parts. This allows to have two-column tables with +multiple entries in the first column. See manual for more details. + +**** ~latex-environment~ elements support ~caption~ keywords for LaTeX export +*** ~org-edit-special~ can edit LaTeX environments + +Using ~C-c '~ on a LaTeX environment opens a sub-editing buffer. By +default, major mode in that buffer is ~latex-mode~, but it can be +changed by configuring ~org-src-lang-modes~. + +*** ~org-list-to-generic~ includes a new property: ~:ifmt~ + +~:ifmt~ is a function to be called on the body of each item. See +~org-list-to-generic~ documentation for details. + +*** New variable : ~org-bibtex-headline-format-function~ +This allow to use a different title than entry title. + +*** ~org-attach~ supports attaching files from URLs + +Using ~C-c C-a u~ prompts for a URL pointing to a file to be attached +to the document. + +*** New option for ~org-refile-use-outline-path~ +~org-refile-use-outline-path~ now supports the setting ~buffer-name~, +which causes refile targets to be prefixed with the buffer’s +name. This is particularly useful when used in conjunction with +~uniquify.el~. + +*** ~org-file-contents~ now allows the FILE argument to be a URL. +This allows ~#+SETUPFILE:~ to accept a URL instead of a local file +path. The URL contents are auto-downloaded and saved to a temporary +cache ~org--file-cache~. A new optional argument ~NOCACHE~ is added +to ~org-file-contents~. + +*** ~org-mode-restart~ now resets the newly added ~org--file-cache~. +Using ~C-c C-c~ on any keyword (like ~#+SETUPFILE~) will reset the +that file cache. + +*** New option : ~org-table-duration-hour-zero-padding~ +This variable allow computed durations in tables to be zero-padded. + +*** New mode switch for table formulas : =U= +This mode omits seconds in durations. + +** Removed functions + +*** Org Timeline + +This feature has been removed. Use a custom agenda view, possibly +narrowed to current buffer to achieve a similar functionality. + +*** ~org-agenda-skip-entry-when-regexp-matches~ is obsolete + +Use ~org-agenda-skip-if~ instead. + +*** ~org-agenda-skip-subtree-when-regexp-matches~ is obsolete + +Use ~org-agenda-skip-if~ instead. + +*** ~org-agenda-skip-entry-when-regexp-matches-in-subtree~ is obsolete + +Use ~org-agenda-skip-if~ instead. + +*** ~org-minutes-to-clocksum-string~ is obsolete + +Use ~org-duration-from-minutes~ instead. + +*** ~org-hh:mm-string-to-minutes~ is obsolete + +Use ~org-duration-to-minutes~ instead. + +*** ~org-duration-string-to-minutes~ is obsolete + +Use ~org-duration-to-minutes~ instead. + +*** ~org-gnus-nnimap-cached-article-number~ is removed. + +This function relied on ~nnimap-group-overview-filename~, which was +removed from Gnus circa September 2010. + +** Removed options + +*** ~org-agenda-repeating-timestamp-show-all~ is removed. + +For an equivalent to a ~nil~ value, set +~org-agenda-show-future-repeats~ to nil and +~org-agenda-prefer-last-repeat~ to ~t~. + +*** ~org-gnus-nnimap-query-article-no-from-file~ is removed. + +This variable has no effect, as it was relying on a function that was +removed from Gnus circa September 2010. + +*** ~org-usenet-links-prefer-google~ is obsolete. + +Use ~org-gnus-prefer-web-links~ instead. + +*** ~org-publish-sitemap-file-entry-format~ is deprecated + +One can provide new ~:sitemap-format-entry~ property for a function +equivalent to the removed format string. + +*** ~org-enable-table-editor~ is removed. + +Setting it to a ~nil~ value broke some other features (e.g., speed +keys). + +*** ~org-export-use-babel~ cannot be set to ~inline-only~ + +The variable is now a boolean. + +*** ~org-texinfo-def-table-markup~ is obsolete + +Use ~org-texinfo-table-default-markup~ instead. + +** New functions + +*** ~org-publish-find-property~ + +This function can be used as a tool to format entries in a site-map, +in addition to ~org-publish-find-title~ and ~org-publish-find-date~. + +*** ~org-list-to-org~ + +It is the reciprocal of ~org-list-to-lisp~, which see. + +*** ~org-agenda-set-restriction-lock-from-agenda~ + +Call ~org-agenda-set-restriction-lock~ from the agenda. + +** Miscellaneous + +*** The Library of Babel now on Worg + +The library-of-babel.org used to be accessible from the =doc/= +directory, distributed with Org’s core. It is now accessible +from the Worg community-driven documentation [[http://orgmode.org/worg/library-of-babel.html][here]]. + +If you want to contribute to it, please see [[http://orgmode.org/worg/org-contribute.html][how to contribute]]. + +*** Allow multiple columns view + +Columns view is not limited to a single buffer anymore. +*** Org Attach obeys ~dired-dwim-target~ + +When a Dired buffer is opened next to the Org document being edited, +the prompt for file to attach can start in the Dired buffer's +directory if `dired-dwim-target' in non-nil. + +*** ~org-fill-paragraph~ can now fill a whole region +*** More specific anniversary descriptions + +Anniversary descriptions (used in the agenda view, for instance) +include the point in time, when the anniversary appears. This is, +in its most general form, just the date of the anniversary. Or +more specific terms, like "today", "tomorrow" or "in n days" are +used to describe the time span. + +This feature allows to automatically change the description of an +anniversary, depending on if it occurs in the next few days or +far away in the future. + +*** Computed dates in tables appear as inactive time stamps + +*** Save point before opening a file with an unknown search option + +When following a file link with a search option (e.g., =::#custom-id=) +that doesn't exist in the target file, save positon before raising an +error. As a consequence, it is possible to jump back to the original +document with ~org-mark-ring-goto~ (default binding =C-c &=). + +*** ~org-get-heading~ accepts two more optional arguments + +See docstring for details. + +*** New option ~org-babel-uppercase-example-markers~ + +This variable is a ~defcustom~ and replaces the variable +~org-babel-capitalize-example-region-markers~, which is a ~defvar~ and +is now obselete. +*** =INCLUDE= keywords in commented trees are now ignored. +*** Default value for ~org-texinfo-text-markup-alist~ changed. + +Now ~=...=~ markup uses ~@samp{}~ instead of ~@verb{}~. You can use +~@verb{}~ again by customizing the variable. +*** Texinfo exports example blocks as ~@example~ +*** Texinfo exports inline src blocks as ~@code{}~ +*** Texinfo default table markup is ~@asis~ +It used to be ~@samp~ but ~@asis~ is neutral and, therefore, more +suitable as a default value. +*** Texinfo default process includes ~--no-split~ option +*** New entities : ~\dollar~ and ~\USD~ +*** ~org-parse-time-string~ accepts a new optional argument +=ZONE= specifies the current time zone. +*** ~org-time-string-to-seconds~ now accepts an optional =ZONE= argument +*** Support for date style URLs in =org-protocol://open-source= + URLs like =https://cool-blog.com/2017/05/20/cool-post/= are + covered by rewrite rules. + +*** Add (C) =COMMENT= support to ~org-structure-template-alist~ + * Version 9.0 ** Incompatible changes diff --git a/etc/refcards/orgcard.tex b/etc/refcards/orgcard.tex index 71d1ef5f907..0880841a945 100644 --- a/etc/refcards/orgcard.tex +++ b/etc/refcards/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{9.0.10} +\def\orgversionnumber{9.1.1} \def\versionyear{2017} % latest update \input emacsver.tex diff --git a/lisp/org/ob-C.el b/lisp/org/ob-C.el index 86047eeeccf..78528a882bc 100644 --- a/lisp/org/ob-C.el +++ b/lisp/org/ob-C.el @@ -46,6 +46,19 @@ (defvar org-babel-default-header-args:C '()) +(defconst org-babel-header-args:C '((includes . :any) + (defines . :any) + (main . :any) + (flags . :any) + (cmdline . :any) + (libs . :any)) + "C/C++-specific header arguments.") + +(defconst org-babel-header-args:C++ + (append '((namespaces . :any)) + org-babel-header-args:C) + "C++-specific header arguments.") + (defcustom org-babel-C-compiler "gcc" "Command used to compile a C source code file into an executable. May be either a command in the path, like gcc @@ -196,15 +209,18 @@ its header arguments." (colnames (cdr (assq :colname-names params))) (main-p (not (string= (cdr (assq :main params)) "no"))) (includes (org-babel-read - (or (cdr (assq :includes params)) - (org-entry-get nil "includes" t)) + (cdr (assq :includes params)) nil)) (defines (org-babel-read - (or (cdr (assq :defines params)) - (org-entry-get nil "defines" t)) - nil))) + (cdr (assq :defines params)) + nil)) + (namespaces (org-babel-read + (cdr (assq :namespaces params)) + nil))) (when (stringp includes) (setq includes (split-string includes))) + (when (stringp namespaces) + (setq namespaces (split-string namespaces))) (when (stringp defines) (let ((y nil) (result (list t))) @@ -224,6 +240,11 @@ its header arguments." (mapconcat (lambda (inc) (format "#define %s" inc)) (if (listp defines) defines (list defines)) "\n") + ;; namespaces + (mapconcat + (lambda (inc) (format "using namespace %s;" inc)) + namespaces + "\n") ;; variables (mapconcat 'org-babel-C-var-to-C vars "\n") ;; table sizes diff --git a/lisp/org/ob-R.el b/lisp/org/ob-R.el index ded825b1d01..6781fb30a3b 100644 --- a/lisp/org/ob-R.el +++ b/lisp/org/ob-R.el @@ -159,10 +159,10 @@ This function is called by `org-babel-execute-src-block'." (result-type (cdr (assq :result-type params))) (session (org-babel-R-initiate-session (cdr (assq :session params)) params)) - (colnames-p (cdr (assq :colnames params))) - (rownames-p (cdr (assq :rownames params))) (graphics-file (and (member "graphics" (assq :result-params params)) (org-babel-graphical-output-file params))) + (colnames-p (unless graphics-file (cdr (assq :colnames params)))) + (rownames-p (unless graphics-file (cdr (assq :rownames params)))) (full-body (let ((inside (list (org-babel-expand-body:R body params graphics-file)))) diff --git a/lisp/org/ob-clojure.el b/lisp/org/ob-clojure.el index b99035b4cce..b49bfe58898 100644 --- a/lisp/org/ob-clojure.el +++ b/lisp/org/ob-clojure.el @@ -2,7 +2,7 @@ ;; Copyright (C) 2009-2017 Free Software Foundation, Inc. -;; Author: Joel Boehland, Eric Schulte, Oleh Krehel +;; Author: Joel Boehland, Eric Schulte, Oleh Krehel, Frederick Giasson ;; ;; Keywords: literate programming, reproducible research ;; Homepage: http://orgmode.org @@ -43,19 +43,34 @@ (require 'ob) (declare-function cider-current-connection "ext:cider-client" (&optional type)) -(declare-function cider-current-session "ext:cider-client" ()) +(declare-function cider-current-ns "ext:cider-client" ()) +(declare-function nrepl--merge "ext:nrepl-client" (dict1 dict2)) (declare-function nrepl-dict-get "ext:nrepl-client" (dict key)) +(declare-function nrepl-dict-put "ext:nrepl-client" (dict key value)) +(declare-function nrepl-request:eval "ext:nrepl-client" + (input callback connection &optional session ns line column additional-params)) (declare-function nrepl-sync-request:eval "ext:nrepl-client" (input connection session &optional ns)) (declare-function org-trim "org" (s &optional keep-lead)) (declare-function slime-eval "ext:slime" (sexp &optional package)) +(defvar nrepl-sync-request-timeout) + (defvar org-babel-tangle-lang-exts) (add-to-list 'org-babel-tangle-lang-exts '("clojure" . "clj")) (defvar org-babel-default-header-args:clojure '()) (defvar org-babel-header-args:clojure '((package . :any))) +(defcustom org-babel-clojure-sync-nrepl-timeout 10 + "Timeout value, in seconds, of a Clojure sync call. +If the value is nil, timeout is disabled." + :group 'org-babel + :type 'integer + :version "26.1" + :package-version '(Org . "9.1") + :safe #'wholenump) + (defcustom org-babel-clojure-backend (cond ((featurep 'cider) 'cider) (t 'slime)) @@ -84,21 +99,86 @@ body))) (defun org-babel-execute:clojure (body params) - "Execute a block of Clojure code with Babel." + "Execute a block of Clojure code with Babel. +The underlying process performed by the code block can be output +using the :show-process parameter." (let ((expanded (org-babel-expand-body:clojure body params)) - result) + (response (list 'dict)) + result) (cl-case org-babel-clojure-backend (cider (require 'cider) - (let ((result-params (cdr (assq :result-params params)))) - (setq result - (nrepl-dict-get - (nrepl-sync-request:eval - expanded (cider-current-connection) (cider-current-session)) - (if (or (member "output" result-params) - (member "pp" result-params)) - "out" - "value"))))) + (let ((result-params (cdr (assq :result-params params))) + (show (cdr (assq :show-process params)))) + (if (member show '(nil "no")) + ;; Run code without showing the process. + (progn + (setq response + (let ((nrepl-sync-request-timeout + org-babel-clojure-sync-nrepl-timeout)) + (nrepl-sync-request:eval expanded + (cider-current-connection) + (cider-current-ns)))) + (setq result + (concat + (nrepl-dict-get response + (if (or (member "output" result-params) + (member "pp" result-params)) + "out" + "value")) + (nrepl-dict-get response "ex") + (nrepl-dict-get response "root-ex") + (nrepl-dict-get response "err")))) + ;; Show the process in an output buffer/window. + (let ((process-buffer (switch-to-buffer-other-window + "*Clojure Show Process Sub Buffer*")) + status) + ;; Run the Clojure code in nREPL. + (nrepl-request:eval + expanded + (lambda (resp) + (when (member "out" resp) + ;; Print the output of the nREPL in the output buffer. + (princ (nrepl-dict-get resp "out") process-buffer)) + (when (member "ex" resp) + ;; In case there is an exception, then add it to the + ;; output buffer as well. + (princ (nrepl-dict-get resp "ex") process-buffer) + (princ (nrepl-dict-get resp "root-ex") process-buffer)) + (when (member "err" resp) + ;; In case there is an error, then add it to the + ;; output buffer as well. + (princ (nrepl-dict-get resp "err") process-buffer)) + (nrepl--merge response resp) + ;; Update the status of the nREPL output session. + (setq status (nrepl-dict-get response "status"))) + (cider-current-connection) + (cider-current-ns)) + + ;; Wait until the nREPL code finished to be processed. + (while (not (member "done" status)) + (nrepl-dict-put response "status" (remove "need-input" status)) + (accept-process-output nil 0.01) + (redisplay)) + + ;; Delete the show buffer & window when the processing is + ;; finalized. + (mapc #'delete-window + (get-buffer-window-list process-buffer nil t)) + (kill-buffer process-buffer) + + ;; Put the output or the value in the result section of + ;; the code block. + (setq result + (concat + (nrepl-dict-get response + (if (or (member "output" result-params) + (member "pp" result-params)) + "out" + "value")) + (nrepl-dict-get response "ex") + (nrepl-dict-get response "root-ex") + (nrepl-dict-get response "err"))))))) (slime (require 'slime) (with-temp-buffer diff --git a/lisp/org/ob-core.el b/lisp/org/ob-core.el index e18716823df..c7c03845451 100644 --- a/lisp/org/ob-core.el +++ b/lisp/org/ob-core.el @@ -82,7 +82,6 @@ (declare-function org-reverse-string "org" (string)) (declare-function org-set-outline-overlay-data "org" (data)) (declare-function org-show-context "org" (&optional key)) -(declare-function org-split-string "org" (string &optional separators)) (declare-function org-src-coderef-format "org-src" (element)) (declare-function org-src-coderef-regexp "org-src" (fmt &optional label)) (declare-function org-table-align "org-table" ()) @@ -179,6 +178,14 @@ This string must include a \"%s\" which will be replaced by the results." :package-version '(Org . "9.0") :safe #'booleanp) +(defcustom org-babel-uppercase-example-markers nil + "When non-nil, begin/end example markers will be inserted in upper case." + :group 'org-babel + :type 'boolean + :version "26.1" + :package-version '(Org . "9.1") + :safe #'booleanp) + (defun org-babel-noweb-wrap (&optional regexp) (concat org-babel-noweb-wrap-start (or regexp "\\([^ \t\n].+?[^ \t]\\|[^ \t\n]\\)") @@ -234,11 +241,9 @@ should be asked whether to allow evaluation." (query (or (equal eval "query") (and export (equal eval "query-export")) (if (functionp org-confirm-babel-evaluate) - (save-excursion - (goto-char (nth 5 info)) - (funcall org-confirm-babel-evaluate - ;; language, code block body - (nth 0 info) (nth 1 info))) + (funcall org-confirm-babel-evaluate + ;; Language, code block body. + (nth 0 info) (nth 1 info)) org-confirm-babel-evaluate)))) (cond (noeval nil) @@ -2348,7 +2353,7 @@ INFO may provide the values of these header arguments (in the ((assq :wrap (nth 2 info)) (let ((name (or (cdr (assq :wrap (nth 2 info))) "RESULTS"))) (funcall wrap (concat "#+BEGIN_" name) - (concat "#+END_" (car (org-split-string name))) + (concat "#+END_" (car (split-string name))) nil nil (concat "{{{results(@@" name ":") "@@)}}}"))) ((member "html" result-params) (funcall wrap "#+BEGIN_EXPORT html" "#+END_EXPORT" nil nil @@ -2483,15 +2488,12 @@ file's directory then expand relative links." result) (if description (concat "[" description "]") "")))) -(defvar org-babel-capitalize-example-region-markers nil - "Make true to capitalize begin/end example markers inserted by code blocks.") - (defun org-babel-examplify-region (beg end &optional results-switches inline) "Comment out region using the inline `==' or `: ' org example quote." (interactive "*r") (let ((maybe-cap (lambda (str) - (if org-babel-capitalize-example-region-markers (upcase str) str)))) + (if org-babel-uppercase-example-markers (upcase str) str)))) (if inline (save-excursion (goto-char beg) diff --git a/lisp/org/ob-exp.el b/lisp/org/ob-exp.el index dc9c53aade6..9606d3e474f 100644 --- a/lisp/org/ob-exp.el +++ b/lisp/org/ob-exp.el @@ -38,19 +38,18 @@ (defvar org-src-preserve-indentation) -(defcustom org-export-babel-evaluate t - "Switch controlling code evaluation during export. +(defcustom org-export-use-babel t + "Switch controlling code evaluation and header processing during export. When set to nil no code will be evaluated as part of the export -process and no header arguments will be obeyed. When set to -`inline-only', only inline code blocks will be executed. Users -who wish to avoid evaluating code on export should use the header -argument `:eval never-export'." +process and no header arguments will be obeyed. Users who wish +to avoid evaluating code on export should use the header argument +`:eval never-export'." :group 'org-babel :version "24.1" :type '(choice (const :tag "Never" nil) - (const :tag "Only inline code" inline-only) - (const :tag "Always" t))) -(put 'org-export-babel-evaluate 'safe-local-variable #'null) + (const :tag "Always" t)) + :safe #'null) + (defmacro org-babel-exp--at-source (&rest body) "Evaluate BODY at the source of the Babel block at point. @@ -128,12 +127,10 @@ this template." (defun org-babel-exp-process-buffer () "Execute all Babel blocks in current buffer." (interactive) - (when org-export-babel-evaluate + (when org-export-use-babel (save-window-excursion (let ((case-fold-search t) - (regexp (if (eq org-export-babel-evaluate 'inline-only) - "\\(call\\|src\\)_" - "\\(call\\|src\\)_\\|^[ \t]*#\\+\\(BEGIN_SRC\\|CALL:\\)")) + (regexp "\\(call\\|src\\)_\\|^[ \t]*#\\+\\(BEGIN_SRC\\|CALL:\\)") ;; Get a pristine copy of current buffer so Babel ;; references are properly resolved and source block ;; context is preserved. diff --git a/lisp/org/ob-gnuplot.el b/lisp/org/ob-gnuplot.el index f35374758f6..763386270d7 100644 --- a/lisp/org/ob-gnuplot.el +++ b/lisp/org/ob-gnuplot.el @@ -40,7 +40,7 @@ ;;; Code: (require 'ob) -(declare-function org-time-string-to-time "org" (s &optional buffer pos)) +(declare-function org-time-string-to-time "org" (s &optional zone)) (declare-function org-combine-plists "org" (&rest plists)) (declare-function orgtbl-to-generic "org-table" (table params)) (declare-function gnuplot-mode "ext:gnuplot-mode" ()) diff --git a/lisp/org/ob-lilypond.el b/lisp/org/ob-lilypond.el index 3320a7e55b4..0cc85685e91 100644 --- a/lisp/org/ob-lilypond.el +++ b/lisp/org/ob-lilypond.el @@ -89,7 +89,7 @@ you can leave the string empty on this case." (string :tag "Lilypond ") (string :tag "PDF Viewer ") (string :tag "MIDI Player")) - :version "24.3" + :version "24.4" :package-version '(Org . "8.2.7") :set (lambda (_symbol value) diff --git a/lisp/org/ob-lua.el b/lisp/org/ob-lua.el index 4fd7a323825..fc9d9f2f0e2 100644 --- a/lisp/org/ob-lua.el +++ b/lisp/org/ob-lua.el @@ -49,7 +49,7 @@ (defcustom org-babel-lua-command "lua" "Name of the command for executing Lua code." - :version "24.5" + :version "26.1" :package-version '(Org . "8.3") :group 'org-babel :type 'string) @@ -58,21 +58,21 @@ "Preferred lua mode for use in running lua interactively. This will typically be 'lua-mode." :group 'org-babel - :version "24.5" + :version "26.1" :package-version '(Org . "8.3") :type 'symbol) (defcustom org-babel-lua-hline-to "None" "Replace hlines in incoming tables with this when translating to lua." :group 'org-babel - :version "24.5" + :version "26.1" :package-version '(Org . "8.3") :type 'string) (defcustom org-babel-lua-None-to 'hline "Replace 'None' in lua tables with this before returning." :group 'org-babel - :version "24.5" + :version "26.1" :package-version '(Org . "8.3") :type 'symbol) diff --git a/lisp/org/ob-maxima.el b/lisp/org/ob-maxima.el index b2680aa7b6f..224b3605035 100644 --- a/lisp/org/ob-maxima.el +++ b/lisp/org/ob-maxima.el @@ -48,9 +48,13 @@ (defun org-babel-maxima-expand (body params) "Expand a block of Maxima code according to its header arguments." - (let ((vars (org-babel--get-vars params))) + (let ((vars (org-babel--get-vars params)) + (epilogue (cdr (assq :epilogue params))) + (prologue (cdr (assq :prologue params)))) (mapconcat 'identity (list + ;; Any code from the specified prologue at the start. + prologue ;; graphic output (let ((graphic-file (ignore-errors (org-babel-graphical-output-file params)))) (if graphic-file @@ -62,6 +66,8 @@ (mapconcat 'org-babel-maxima-var-to-maxima vars "\n") ;; body body + ;; Any code from the specified epilogue at the end. + epilogue "gnuplot_close ()$") "\n"))) diff --git a/lisp/org/ob-plantuml.el b/lisp/org/ob-plantuml.el index 20dc25f6484..8093100edaf 100644 --- a/lisp/org/ob-plantuml.el +++ b/lisp/org/ob-plantuml.el @@ -46,6 +46,31 @@ :version "24.1" :type 'string) +(defun org-babel-variable-assignments:plantuml (params) + "Return a list of PlantUML statements assigning the block's variables. +PARAMS is a property list of source block parameters, which may +contain multiple entries for the key `:var'. `:var' entries in PARAMS +are expected to be scalar variables." + (mapcar + (lambda (pair) + (format "!define %s %s" + (car pair) + (replace-regexp-in-string "\"" "" (cdr pair)))) + (org-babel--get-vars params))) + +(defun org-babel-plantuml-make-body (body params) + "Return PlantUML input string. +BODY is the content of the source block and PARAMS is a property list +of source block parameters. This function relies on the +`org-babel-expand-body:generic' function to extract `:var' entries +from PARAMS and on the `org-babel-variable-assignments:plantuml' +function to convert variables to PlantUML assignments." + (concat + "@startuml\n" + (org-babel-expand-body:generic + body params (org-babel-variable-assignments:plantuml params)) + "\n@enduml")) + (defun org-babel-execute:plantuml (body params) "Execute a block of plantuml code with org-babel. This function is called by `org-babel-execute-src-block'." @@ -54,6 +79,7 @@ This function is called by `org-babel-execute-src-block'." (cmdline (cdr (assq :cmdline params))) (in-file (org-babel-temp-file "plantuml-")) (java (or (cdr (assq :java params)) "")) + (full-body (org-babel-plantuml-make-body body params)) (cmd (if (string= "" org-plantuml-jar-path) (error "`org-plantuml-jar-path' is not set") (concat "java " java " -jar " @@ -85,7 +111,7 @@ This function is called by `org-babel-execute-src-block'." (org-babel-process-file-name out-file))))) (unless (file-exists-p org-plantuml-jar-path) (error "Could not find plantuml.jar at %s" org-plantuml-jar-path)) - (with-temp-file in-file (insert (concat "@startuml\n" body "\n@enduml"))) + (with-temp-file in-file (insert full-body)) (message "%s" cmd) (org-babel-eval cmd "") nil)) ;; signal that output has already been written to file diff --git a/lisp/org/ob-scheme.el b/lisp/org/ob-scheme.el index 2782853220b..f67080adfd3 100644 --- a/lisp/org/ob-scheme.el +++ b/lisp/org/ob-scheme.el @@ -44,37 +44,51 @@ (defvar geiser-impl--implementation) ; Defined in geiser-impl.el (defvar geiser-default-implementation) ; Defined in geiser-impl.el (defvar geiser-active-implementations) ; Defined in geiser-impl.el +(defvar geiser-debug-show-debug-p) ; Defined in geiser-debug.el +(defvar geiser-debug-jump-to-debug-p) ; Defined in geiser-debug.el +(defvar geiser-repl-use-other-window) ; Defined in geiser-repl.el +(defvar geiser-repl-window-allow-split) ; Defined in geiser-repl.el (declare-function run-geiser "ext:geiser-repl" (impl)) (declare-function geiser-mode "ext:geiser-mode" ()) (declare-function geiser-eval-region "ext:geiser-mode" (start end &optional and-go raw nomsg)) (declare-function geiser-repl-exit "ext:geiser-repl" (&optional arg)) +(declare-function geiser-eval--retort-output "ext:geiser-eval" (ret)) +(declare-function geiser-eval--retort-result-str "ext:geiser-eval" (ret prefix)) + +(defcustom org-babel-scheme-null-to 'hline + "Replace `null' and empty lists in scheme tables with this before returning." + :group 'org-babel + :version "26.1" + :package-version '(Org . "9.1") + :type 'symbol) (defvar org-babel-default-header-args:scheme '() "Default header arguments for scheme code blocks.") (defun org-babel-expand-body:scheme (body params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (org-babel--get-vars params))) - (if (> (length vars) 0) - (concat "(let (" - (mapconcat - (lambda (var) (format "%S" (print `(,(car var) ',(cdr var))))) - vars "\n ") - ")\n" body ")") - body))) - - -(defvar org-babel-scheme-repl-map (make-hash-table :test 'equal) + (let ((vars (org-babel--get-vars params)) + (prepends (cdr (assq :prologue params)))) + (concat (and prepends (concat prepends "\n")) + (if (null vars) body + (format "(let (%s)\n%s\n)" + (mapconcat + (lambda (var) + (format "%S" (print `(,(car var) ',(cdr var))))) + vars + "\n ") + body))))) + + +(defvar org-babel-scheme-repl-map (make-hash-table :test #'equal) "Map of scheme sessions to session names.") (defun org-babel-scheme-cleanse-repl-map () "Remove dead buffers from the REPL map." (maphash - (lambda (x y) - (when (not (buffer-name y)) - (remhash x org-babel-scheme-repl-map))) + (lambda (x y) (unless (buffer-name y) (remhash x org-babel-scheme-repl-map))) org-babel-scheme-repl-map)) (defun org-babel-scheme-get-session-buffer (session-name) @@ -112,12 +126,9 @@ If the session is unnamed (nil), generate a name. If the session is `none', use nil for the session name, and org-babel-scheme-execute-with-geiser will use a temporary session." - (let ((result - (cond ((not name) - (concat buffer " " (symbol-name impl) " REPL")) - ((string= name "none") nil) - (name)))) - result)) + (cond ((not name) (concat buffer " " (symbol-name impl) " REPL")) + ((string= name "none") nil) + (name))) (defmacro org-babel-scheme-capture-current-message (&rest body) "Capture current message in both interactive and noninteractive mode" @@ -145,37 +156,46 @@ is true; otherwise returns the last value." (with-temp-buffer (insert (format ";; -*- geiser-scheme-implementation: %s -*-" impl)) (newline) - (insert (if output - (format "(with-output-to-string (lambda () %s))" code) - code)) + (insert code) (geiser-mode) - (let ((repl-buffer (save-current-buffer - (org-babel-scheme-get-repl impl repl)))) - (when (not (eq impl (org-babel-scheme-get-buffer-impl - (current-buffer)))) - (message "Implementation mismatch: %s (%s) %s (%s)" impl (symbolp impl) - (org-babel-scheme-get-buffer-impl (current-buffer)) - (symbolp (org-babel-scheme-get-buffer-impl - (current-buffer))))) - (setq geiser-repl--repl repl-buffer) - (setq geiser-impl--implementation nil) - (setq result (org-babel-scheme-capture-current-message - (geiser-eval-region (point-min) (point-max)))) - (setq result - (if (and (stringp result) (equal (substring result 0 3) "=> ")) - (replace-regexp-in-string "^=> " "" result) - "\"An error occurred.\"")) - (when (not repl) - (save-current-buffer (set-buffer repl-buffer) - (geiser-repl-exit)) - (set-process-query-on-exit-flag (get-buffer-process repl-buffer) nil) - (kill-buffer repl-buffer)) - (setq result (if (or (string= result "#") - (string= result "#")) - nil - result)))) + (let ((geiser-repl-window-allow-split nil) + (geiser-repl-use-other-window nil)) + (let ((repl-buffer (save-current-buffer + (org-babel-scheme-get-repl impl repl)))) + (when (not (eq impl (org-babel-scheme-get-buffer-impl + (current-buffer)))) + (message "Implementation mismatch: %s (%s) %s (%s)" impl (symbolp impl) + (org-babel-scheme-get-buffer-impl (current-buffer)) + (symbolp (org-babel-scheme-get-buffer-impl + (current-buffer))))) + (setq geiser-repl--repl repl-buffer) + (setq geiser-impl--implementation nil) + (let ((geiser-debug-jump-to-debug-p nil) + (geiser-debug-show-debug-p nil)) + (let ((ret (geiser-eval-region (point-min) (point-max)))) + (setq result (if output + (geiser-eval--retort-output ret) + (geiser-eval--retort-result-str ret ""))))) + (when (not repl) + (save-current-buffer (set-buffer repl-buffer) + (geiser-repl-exit)) + (set-process-query-on-exit-flag (get-buffer-process repl-buffer) nil) + (kill-buffer repl-buffer))))) result)) +(defun org-babel-scheme--table-or-string (results) + "Convert RESULTS into an appropriate elisp value. +If the results look like a list or tuple, then convert them into an +Emacs-lisp table, otherwise return the results as a string." + (let ((res (org-babel-script-escape results))) + (cond ((listp res) + (mapcar (lambda (el) + (if (or (null el) (eq el 'null)) + org-babel-scheme-null-to + el)) + res)) + (t res)))) + (defun org-babel-execute:scheme (body params) "Execute a block of Scheme code with org-babel. This function is called by `org-babel-execute-src-block'" @@ -184,24 +204,28 @@ This function is called by `org-babel-execute-src-block'" "^ ?\\*\\([^*]+\\)\\*" "\\1" (buffer-name source-buffer)))) (save-excursion - (org-babel-reassemble-table - (let* ((result-type (cdr (assq :result-type params))) - (impl (or (when (cdr (assq :scheme params)) - (intern (cdr (assq :scheme params)))) - geiser-default-implementation - (car geiser-active-implementations))) - (session (org-babel-scheme-make-session-name - source-buffer-name (cdr (assq :session params)) impl)) - (full-body (org-babel-expand-body:scheme body params))) - (org-babel-scheme-execute-with-geiser - full-body ; code - (string= result-type "output") ; output? - impl ; implementation - (and (not (string= session "none")) session))) ; session - (org-babel-pick-name (cdr (assq :colname-names params)) - (cdr (assq :colnames params))) - (org-babel-pick-name (cdr (assq :rowname-names params)) - (cdr (assq :rownames params))))))) + (let* ((result-type (cdr (assq :result-type params))) + (impl (or (when (cdr (assq :scheme params)) + (intern (cdr (assq :scheme params)))) + geiser-default-implementation + (car geiser-active-implementations))) + (session (org-babel-scheme-make-session-name + source-buffer-name (cdr (assq :session params)) impl)) + (full-body (org-babel-expand-body:scheme body params)) + (result + (org-babel-scheme-execute-with-geiser + full-body ; code + (string= result-type "output") ; output? + impl ; implementation + (and (not (string= session "none")) session)))) ; session + (let ((table + (org-babel-reassemble-table + result + (org-babel-pick-name (cdr (assq :colname-names params)) + (cdr (assq :colnames params))) + (org-babel-pick-name (cdr (assq :rowname-names params)) + (cdr (assq :rownames params)))))) + (org-babel-scheme--table-or-string table)))))) (provide 'ob-scheme) diff --git a/lisp/org/ob-sql.el b/lisp/org/ob-sql.el index 7c3ee120d77..9250825d4e5 100644 --- a/lisp/org/ob-sql.el +++ b/lisp/org/ob-sql.el @@ -43,15 +43,25 @@ ;; - colnames (default, nil, means "yes") ;; - result-params ;; - out-file +;; ;; The following are used but not really implemented for SQL: ;; - colname-names ;; - rownames ;; - rowname-names ;; +;; Engines supported: +;; - mysql +;; - dbi +;; - mssql +;; - sqsh +;; - postgresql +;; - oracle +;; - vertica +;; ;; TODO: ;; ;; - support for sessions -;; - support for more engines (currently only supports mysql) +;; - support for more engines ;; - what's a reasonable way to drop table data into SQL? ;; @@ -116,6 +126,28 @@ SQL Server on Windows and Linux platform." (when database (format "-d \"%s\"" database)))) " ")) +(defun org-babel-sql-dbstring-sqsh (host user password database) + "Make sqsh commmand line args for database connection. +\"sqsh\" is one method to access Sybase or MS SQL via Linux platform" + (mapconcat #'identity + (delq nil + (list (when host (format "-S \"%s\"" host)) + (when user (format "-U \"%s\"" user)) + (when password (format "-P \"%s\"" password)) + (when database (format "-D \"%s\"" database)))) + " ")) + +(defun org-babel-sql-dbstring-vertica (host port user password database) + "Make Vertica command line args for database connection. Pass nil to omit that arg." + (mapconcat #'identity + (delq nil + (list (when host (format "-h %s" host)) + (when port (format "-p %d" port)) + (when user (format "-U %s" user)) + (when password (format "-w %s" (shell-quote-argument password) )) + (when database (format "-d %s" database)))) + " ")) + (defun org-babel-sql-convert-standard-filename (file) "Convert FILE to OS standard file name. If in Cygwin environment, uses Cygwin specific function to @@ -179,6 +211,20 @@ footer=off -F \"\t\" %s -f %s -o %s %s" (org-babel-process-file-name in-file) (org-babel-process-file-name out-file) (or cmdline ""))) + (`sqsh (format "sqsh %s %s -i %s -o %s -m csv" + (or cmdline "") + (org-babel-sql-dbstring-sqsh + dbhost dbuser dbpassword database) + (org-babel-sql-convert-standard-filename + (org-babel-process-file-name in-file)) + (org-babel-sql-convert-standard-filename + (org-babel-process-file-name out-file)))) + (`vertica (format "vsql %s -f %s -o %s %s" + (org-babel-sql-dbstring-vertica + dbhost dbport dbuser dbpassword database) + (org-babel-process-file-name in-file) + (org-babel-process-file-name out-file) + (or cmdline ""))) (`oracle (format "sqlplus -s %s < %s > %s" (org-babel-sql-dbstring-oracle @@ -203,18 +249,21 @@ SET MARKUP HTML OFF SPOOL OFF SET COLSEP '|' ") - (`mssql "SET NOCOUNT ON + ((or `mssql `sqsh) "SET NOCOUNT ON ") + (`vertica "\\a\n") (_ "")) - (org-babel-expand-body:sql body params))) + (org-babel-expand-body:sql body params) + ;; "sqsh" requires "go" inserted at EOF. + (if (string= engine "sqsh") "\ngo" ""))) (org-babel-eval command "") (org-babel-result-cond result-params (with-temp-buffer (progn (insert-file-contents-literally out-file) (buffer-string))) (with-temp-buffer (cond - ((memq (intern engine) '(dbi mysql postgresql)) + ((memq (intern engine) '(dbi mysql postgresql sqsh vertica)) ;; Add header row delimiter after column-names header in first line (cond (colnames-p @@ -239,7 +288,7 @@ SET COLSEP '|' (goto-char (point-max)) (forward-char -1)) (write-file out-file)))) - (org-table-import out-file '(16)) + (org-table-import out-file (if (string= engine "sqsh") '(4) '(16))) (org-babel-reassemble-table (mapcar (lambda (x) (if (string= (car x) header-delim) diff --git a/lisp/org/ob-sqlite.el b/lisp/org/ob-sqlite.el index 50e8ac1ab90..38058274a9a 100644 --- a/lisp/org/ob-sqlite.el +++ b/lisp/org/ob-sqlite.el @@ -123,10 +123,7 @@ This function is called by `org-babel-execute-src-block'." (if (listp val) (let ((data-file (org-babel-temp-file "sqlite-data-"))) (with-temp-file data-file - (insert (orgtbl-to-csv - val '(:fmt (lambda (el) (if (stringp el) - el - (format "%S" el))))))) + (insert (orgtbl-to-csv val nil))) data-file) (if (stringp val) val (format "%S" val)))) body))) diff --git a/lisp/org/ob-tangle.el b/lisp/org/ob-tangle.el index ed09ff563a8..adc6806766d 100644 --- a/lisp/org/ob-tangle.el +++ b/lisp/org/ob-tangle.el @@ -29,13 +29,13 @@ (require 'cl-lib) (require 'org-src) +(require 'org-macs) (declare-function make-directory "files" (dir &optional parents)) (declare-function org-at-heading-p "org" (&optional ignored)) (declare-function org-babel-update-block-body "ob-core" (new-body)) (declare-function org-back-to-heading "org" (&optional invisible-ok)) (declare-function org-before-first-heading-p "org" ()) -(declare-function org-edit-special "org" (&optional arg)) (declare-function org-element-at-point "org-element" ()) (declare-function org-element-type "org-element" (element)) (declare-function org-fill-template "org" (template alist)) @@ -45,7 +45,6 @@ (declare-function org-open-link-from-string "org" (s &optional arg reference-buffer)) (declare-function org-remove-indentation "org" (code &optional n)) (declare-function org-store-link "org" (arg)) -(declare-function org-string-nw-p "org-macs" (s)) (declare-function org-trim "org" (s &optional keep-lead)) (declare-function outline-previous-heading "outline" ()) (declare-function org-id-find "org-id" (id &optional markerp)) diff --git a/lisp/org/org-agenda.el b/lisp/org/org-agenda.el index a1ff76b36db..cf7a4dbf38b 100644 --- a/lisp/org/org-agenda.el +++ b/lisp/org/org-agenda.el @@ -277,10 +277,7 @@ list are are :deadline List deadline due on that date. When the date is today, also list any deadlines past due, or due within - `org-deadline-warning-days'. `:deadline' must appear before - `:scheduled' if the setting of - `org-agenda-skip-scheduled-if-deadline-is-shown' is to have - any effect. + `org-deadline-warning-days'. :deadline* Same as above, but only include the deadline if it has an hour specification as [h]h:mm. @@ -327,12 +324,14 @@ the daily/weekly agenda, see `org-agenda-skip-function'.") (string)) (list :tag "Number of days in agenda" (const org-agenda-span) - (choice (const :tag "Day" day) - (const :tag "Week" week) - (const :tag "Fortnight" fortnight) - (const :tag "Month" month) - (const :tag "Year" year) - (integer :tag "Custom"))) + (list + (const :format "" quote) + (choice (const :tag "Day" day) + (const :tag "Week" week) + (const :tag "Fortnight" fortnight) + (const :tag "Month" month) + (const :tag "Year" year) + (integer :tag "Custom")))) (list :tag "Fixed starting date" (const org-agenda-start-day) (string :value "2007-11-01")) @@ -975,18 +974,6 @@ will only be dimmed." (const :tag "Dim to a gray face" t) (const :tag "Make invisible" invisible))) -(defcustom org-timeline-show-empty-dates 3 - "Non-nil means `org-timeline' also shows dates without an entry. -When nil, only the days which actually have entries are shown. -When t, all days between the first and the last date are shown. -When an integer, show also empty dates, but if there is a gap of more than -N days, just insert a special line indicating the size of the gap." - :group 'org-agenda-skip - :type '(choice - (const :tag "None" nil) - (const :tag "All" t) - (integer :tag "at most"))) - (defgroup org-agenda-startup nil "Options concerning initial settings in the Agenda in Org Mode." :tag "Org Agenda Startup" @@ -1081,7 +1068,7 @@ have been removed when this is called, as will any matches for regular expressions listed in `org-agenda-entry-text-exclude-regexps'.") (defvar org-agenda-include-inactive-timestamps nil - "Non-nil means include inactive time stamps in agenda and timeline. + "Non-nil means include inactive time stamps in agenda. Dynamically scoped.") (defgroup org-agenda-windows nil @@ -1155,17 +1142,17 @@ When nil, only the days which actually have entries are shown." (defcustom org-agenda-format-date 'org-agenda-format-date-aligned "Format string for displaying dates in the agenda. -Used by the daily/weekly agenda and by the timeline. This should be -a format string understood by `format-time-string', or a function returning -the formatted date as a string. The function must take a single argument, -a calendar-style date list like (month day year)." +Used by the daily/weekly agenda. This should be a format string +understood by `format-time-string', or a function returning the +formatted date as a string. The function must take a single +argument, a calendar-style date list like (month day year)." :group 'org-agenda-daily/weekly :type '(choice (string :tag "Format string") (function :tag "Function"))) (defun org-agenda-format-date-aligned (date) - "Format a DATE string for display in the daily/weekly agenda, or timeline. + "Format a DATE string for display in the daily/weekly agenda. This function makes sure that dates are aligned for easy reading." (require 'cal-iso) (let* ((dayname (calendar-day-name date)) @@ -1225,8 +1212,7 @@ For example, 9:30am would become 09:30 rather than 9:30." (defcustom org-agenda-weekend-days '(6 0) "Which days are weekend? -These days get the special face `org-agenda-date-weekend' in the agenda -and timeline buffers." +These days get the special face `org-agenda-date-weekend' in the agenda." :group 'org-agenda-daily/weekly :type '(set :greedy t (const :tag "Monday" 1) @@ -1260,17 +1246,43 @@ Custom commands can set this variable in the options section." :version "24.1" :type 'boolean) -(defcustom org-agenda-repeating-timestamp-show-all t - "Non-nil means show all occurrences of a repeating stamp in the agenda. -When set to a list of strings, only show occurrences of repeating -stamps for these TODO keywords. When nil, only one occurrence is -shown, either today or the nearest into the future." +(defcustom org-agenda-show-future-repeats t + "Non-nil shows repeated entries in the future part of the agenda. +When set to the symbol `next' only the first future repeat is shown." + :group 'org-agenda-daily/weekly + :type '(choice + (const :tag "Show all repeated entries" t) + (const :tag "Show next repeated entry" next) + (const :tag "Do not show repeated entries" nil)) + :version "26.1" + :package-version '(Org . "9.1") + :safe #'symbolp) + +(defcustom org-agenda-prefer-last-repeat nil + "Non-nil sets date for repeated entries to their last repeat. + +When nil, display SCHEDULED and DEADLINE dates at their base +date, and in today's agenda, as a reminder. Display plain +time-stamps, on the other hand, at every repeat date in the past +in addition to the base date. + +When non-nil, show a repeated entry at its latest repeat date, +possibly being today even if it wasn't marked as done. This +setting is useful if you do not always mark repeated entries as +done and, yet, consider that reaching repeat date starts the task +anew. + +When set to a list of strings, prefer last repeats only for +entries with these TODO keywords." :group 'org-agenda-daily/weekly :type '(choice - (const :tag "Show repeating stamps" t) - (repeat :tag "Show repeating stamps for these TODO keywords" - (string :tag "TODO Keyword")) - (const :tag "Don't show repeating stamps" nil))) + (const :tag "Prefer last repeat" t) + (const :tag "Prefer base date" nil) + (repeat :tag "Prefer last repeat for entries with these TODO keywords" + (string :tag "TODO keyword"))) + :version "26.1" + :package-version '(Org . "9.1") + :safe (lambda (x) (or (booleanp x) (consp x)))) (defcustom org-scheduled-past-days 10000 "Number of days to continue listing scheduled items not marked DONE. @@ -1278,7 +1290,19 @@ When an item is scheduled on a date, it shows up in the agenda on this day and will be listed until it is marked done or for the number of days given here." :group 'org-agenda-daily/weekly - :type 'integer) + :type 'integer + :safe 'integerp) + +(defcustom org-deadline-past-days 10000 + "Number of days to warn about missed deadlines. +When an item has deadline on a date, it shows up in the agenda on +this day and will appear as a reminder until it is marked DONE or +for the number of days given here." + :group 'org-agenda-daily/weekly + :type 'integer + :version "26.1" + :package-version '(Org . "9.1") + :safe 'integerp) (defcustom org-agenda-log-mode-items '(closed clock) "List of items that should be shown in agenda log mode. @@ -1421,7 +1445,7 @@ E.g. when this is set to 1, the search view will only show headlines of level 1. When set to 0, the default value, don't limit agenda view by outline level." :group 'org-agenda-search-view - :version "24.4" + :version "26.1" :package-version '(Org . "8.3") :type 'integer) @@ -1453,11 +1477,12 @@ the variable `org-agenda-time-grid'." (defcustom org-agenda-time-grid '((daily today require-timed) - "----------------" - (800 1000 1200 1400 1600 1800 2000)) + (800 1000 1200 1400 1600 1800 2000) + "......" + "----------------") "The settings for time grid for agenda display. -This is a list of three items. The first item is again a list. It contains +This is a list of four items. The first item is again a list. It contains symbols specifying conditions when the grid should be displayed: daily if the agenda shows a single day @@ -1466,10 +1491,14 @@ symbols specifying conditions when the grid should be displayed: require-timed show grid only if at least one item has a time specification remove-match skip grid times already present in an entry -The second item is a string which will be placed behind the grid time. +The second item is a list of integers, indicating the times that +should have a grid line. -The third item is a list of integers, indicating the times that should have -a grid line." +The third item is a string which will be placed right after the +times that have a grid line. + +The fourth item is a string placed after the grid times. This +will align with agenda items" :group 'org-agenda-time-grid :type '(list @@ -1481,8 +1510,9 @@ a grid line." require-timed) (const :tag "Skip grid times already present in an entry" remove-match)) - (string :tag "Grid String") - (repeat :tag "Grid Times" (integer :tag "Time")))) + (repeat :tag "Grid Times" (integer :tag "Time")) + (string :tag "Grid String (after agenda times)") + (string :tag "Grid String (aligns with agenda items)"))) (defcustom org-agenda-show-current-time-in-grid t "Non-nil means show the current time in the time grid." @@ -1610,13 +1640,12 @@ When nil, such items are sorted as 0 minutes effort." (defcustom org-agenda-prefix-format '((agenda . " %i %-12:c%?-12t% s") - (timeline . " % s") (todo . " %i %-12:c") (tags . " %i %-12:c") (search . " %i %-12:c")) "Format specifications for the prefix of items in the agenda views. An alist with five entries, each for the different agenda types. The -keys of the sublists are `agenda', `timeline', `todo', `search' and `tags'. +keys of the sublists are `agenda', `todo', `search' and `tags'. The values are format strings. This format works similar to a printf format, with the following meaning: @@ -1669,11 +1698,12 @@ Custom commands can set this variable in the options section." (string :tag "General format") (list :greedy t :tag "View dependent" (cons (const agenda) (string :tag "Format")) - (cons (const timeline) (string :tag "Format")) (cons (const todo) (string :tag "Format")) (cons (const tags) (string :tag "Format")) (cons (const search) (string :tag "Format")))) - :group 'org-agenda-line-format) + :group 'org-agenda-line-format + :version "26.1" + :package-version '(Org . "9.1")) (defvar org-prefix-format-compiled nil "The compiled prefix format and associated variables. @@ -1795,7 +1825,7 @@ given agenda type. This can be set to a list of agenda types in which the agenda must display the inherited tags. Available types are `todo', -`agenda', `search' and `timeline'. +`agenda' and `search'. When set to nil, never show inherited tags in agenda lines." :group 'org-agenda-line-format @@ -1807,7 +1837,7 @@ When set to nil, never show inherited tags in agenda lines." (repeat :tag "Show inherited tags only in selected agenda types" (symbol :tag "Agenda type")))) -(defcustom org-agenda-use-tag-inheritance '(todo search timeline agenda) +(defcustom org-agenda-use-tag-inheritance '(todo search agenda) "List of agenda view types where to use tag inheritance. In tags/tags-todo/tags-tree agenda views, tag inheritance is @@ -1816,7 +1846,7 @@ controlled by `org-use-tag-inheritance'. In other agenda types, agenda entries. Still, you may want the agenda to be aware of the inherited tags anyway, e.g. for later tag filtering. -Allowed value are `todo', `search', `timeline' and `agenda'. +Allowed value are `todo', `search' and `agenda'. This variable has no effect if `org-agenda-show-inherited-tags' is set to `always'. In that case, the agenda is aware of those @@ -1825,7 +1855,8 @@ tags. The default value sets tags in every agenda type. Setting this option to nil will speed up non-tags agenda view a lot." :group 'org-agenda - :version "24.3" + :version "26.1" + :package-version '(Org . "9.1") :type '(choice (const :tag "Use tag inheritance in all agenda types" t) (repeat :tag "Use tag inheritance in selected agenda types" @@ -1854,13 +1885,21 @@ When this is the symbol `prefix', only remove tags when (defvaralias 'org-agenda-remove-tags-when-in-prefix 'org-agenda-remove-tags) -(defcustom org-agenda-tags-column -80 +(defcustom org-agenda-tags-column 'auto "Shift tags in agenda items to this column. -If this number is positive, it specifies the column. If it is negative, -it means that the tags should be flushright to that column. For example, --80 works well for a normal 80 character screen." +If set to `auto', tags will be automatically aligned to the right +edge of the window. + +If set to a positive number, tags will be left-aligned to that +column. If set to a negative number, tags will be right-aligned +to that column. For example, -80 works well for a normal 80 +character screen." :group 'org-agenda-line-format - :type 'integer) + :type '(choice + (const :tag "Automatically align to right edge of window" auto) + (integer :tag "Specific column" -80)) + :package-version '(Org . "9.1") + :version "26.1") (defvaralias 'org-agenda-align-tags-to-column 'org-agenda-tags-column) @@ -2259,7 +2298,7 @@ The following commands are available: (org-defkey org-agenda-mode-map "!" 'org-agenda-toggle-deadlines) (org-defkey org-agenda-mode-map "G" 'org-agenda-toggle-time-grid) (org-defkey org-agenda-mode-map "r" 'org-agenda-redo) -(org-defkey org-agenda-mode-map "g" (lambda () (interactive) (org-agenda-redo t))) +(org-defkey org-agenda-mode-map "g" 'org-agenda-redo-all) (org-defkey org-agenda-mode-map "e" 'org-agenda-set-effort) (org-defkey org-agenda-mode-map "\C-c\C-xe" 'org-agenda-set-effort) (org-defkey org-agenda-mode-map "\C-c\C-x\C-e" @@ -2310,6 +2349,7 @@ The following commands are available: (org-defkey org-agenda-mode-map "b" 'org-agenda-earlier) (org-defkey org-agenda-mode-map "\C-c\C-x\C-c" 'org-agenda-columns) (org-defkey org-agenda-mode-map "\C-c\C-x>" 'org-agenda-remove-restriction-lock) +(org-defkey org-agenda-mode-map "\C-c\C-x<" 'org-agenda-set-restriction-lock-from-agenda) (org-defkey org-agenda-mode-map "[" 'org-agenda-manipulate-query-add) (org-defkey org-agenda-mode-map "]" 'org-agenda-manipulate-query-subtract) @@ -2323,6 +2363,7 @@ The following commands are available: (org-defkey org-agenda-mode-map "<" 'org-agenda-filter-by-category) (org-defkey org-agenda-mode-map "^" 'org-agenda-filter-by-top-headline) (org-defkey org-agenda-mode-map ";" 'org-timer-set-timer) +(org-defkey org-agenda-mode-map "\C-c\C-x_" 'org-timer-stop) (define-key org-agenda-mode-map "?" 'org-agenda-show-the-flagging-note) (org-defkey org-agenda-mode-map "\C-c\C-x\C-mg" 'org-mobile-pull) (org-defkey org-agenda-mode-map "\C-c\C-x\C-mp" 'org-mobile-push) @@ -2340,7 +2381,7 @@ The following commands are available: ("Agenda Files") "--" ("Agenda Dates" - ["Goto Today" org-agenda-goto-today (org-agenda-check-type nil 'agenda 'timeline)] + ["Goto Today" org-agenda-goto-today (org-agenda-check-type nil 'agenda)] ["Next Dates" org-agenda-later (org-agenda-check-type nil 'agenda)] ["Previous Dates" org-agenda-earlier (org-agenda-check-type nil 'agenda)] ["Jump to date" org-agenda-goto-date (org-agenda-check-type nil 'agenda)]) @@ -2386,7 +2427,7 @@ The following commands are available: "--" ["Show Logbook entries" org-agenda-log-mode :style toggle :selected org-agenda-show-log - :active (org-agenda-check-type nil 'agenda 'timeline) + :active (org-agenda-check-type nil 'agenda) :keys "v l (or just l)"] ["Include archived trees" org-agenda-archives-mode :style toggle :selected org-agenda-archives-mode :active t @@ -2443,13 +2484,13 @@ The following commands are available: ["Schedule" org-agenda-schedule t] ["Set Deadline" org-agenda-deadline t] "--" - ["Change Date +1 day" org-agenda-date-later (org-agenda-check-type nil 'agenda 'timeline)] - ["Change Date -1 day" org-agenda-date-earlier (org-agenda-check-type nil 'agenda 'timeline)] - ["Change Time +1 hour" org-agenda-do-date-later :active (org-agenda-check-type nil 'agenda 'timeline) :keys "C-u S-right"] - ["Change Time -1 hour" org-agenda-do-date-earlier :active (org-agenda-check-type nil 'agenda 'timeline) :keys "C-u S-left"] - ["Change Time + min" org-agenda-date-later :active (org-agenda-check-type nil 'agenda 'timeline) :keys "C-u C-u S-right"] - ["Change Time - min" org-agenda-date-earlier :active (org-agenda-check-type nil 'agenda 'timeline) :keys "C-u C-u S-left"] - ["Change Date to ..." org-agenda-date-prompt (org-agenda-check-type nil 'agenda 'timeline)]) + ["Change Date +1 day" org-agenda-date-later (org-agenda-check-type nil 'agenda)] + ["Change Date -1 day" org-agenda-date-earlier (org-agenda-check-type nil 'agenda)] + ["Change Time +1 hour" org-agenda-do-date-later :active (org-agenda-check-type nil 'agenda) :keys "C-u S-right"] + ["Change Time -1 hour" org-agenda-do-date-earlier :active (org-agenda-check-type nil 'agenda) :keys "C-u S-left"] + ["Change Time + min" org-agenda-date-later :active (org-agenda-check-type nil 'agenda) :keys "C-u C-u S-right"] + ["Change Time - min" org-agenda-date-earlier :active (org-agenda-check-type nil 'agenda) :keys "C-u C-u S-left"] + ["Change Date to ..." org-agenda-date-prompt (org-agenda-check-type nil 'agenda)]) ("Clock and Effort" ["Clock in" org-agenda-clock-in t] ["Clock out" org-agenda-clock-out t] @@ -2465,12 +2506,12 @@ The following commands are available: ["Decrease Priority" org-agenda-priority-down t] ["Show Priority" org-show-priority t]) ("Calendar/Diary" - ["New Diary Entry" org-agenda-diary-entry (org-agenda-check-type nil 'agenda 'timeline)] - ["Goto Calendar" org-agenda-goto-calendar (org-agenda-check-type nil 'agenda 'timeline)] - ["Phases of the Moon" org-agenda-phases-of-moon (org-agenda-check-type nil 'agenda 'timeline)] - ["Sunrise/Sunset" org-agenda-sunrise-sunset (org-agenda-check-type nil 'agenda 'timeline)] - ["Holidays" org-agenda-holidays (org-agenda-check-type nil 'agenda 'timeline)] - ["Convert" org-agenda-convert-date (org-agenda-check-type nil 'agenda 'timeline)] + ["New Diary Entry" org-agenda-diary-entry (org-agenda-check-type nil 'agenda)] + ["Goto Calendar" org-agenda-goto-calendar (org-agenda-check-type nil 'agenda)] + ["Phases of the Moon" org-agenda-phases-of-moon (org-agenda-check-type nil 'agenda)] + ["Sunrise/Sunset" org-agenda-sunrise-sunset (org-agenda-check-type nil 'agenda)] + ["Holidays" org-agenda-holidays (org-agenda-check-type nil 'agenda)] + ["Convert" org-agenda-convert-date (org-agenda-check-type nil 'agenda)] "--" ["Create iCalendar File" org-icalendar-combine-agenda-files t]) "--" @@ -2606,8 +2647,7 @@ type." (const agenda) (const todo) (const tags) - (const search) - (const timeline)) + (const search)) (integer :tag "Max number of entries"))))) (defcustom org-agenda-max-todos nil @@ -2625,8 +2665,7 @@ type." (const agenda) (const todo) (const tags) - (const search) - (const timeline)) + (const search)) (integer :tag "Max number of TODOs"))))) (defcustom org-agenda-max-tags nil @@ -2644,8 +2683,7 @@ type." (const agenda) (const todo) (const tags) - (const search) - (const timeline)) + (const search)) (integer :tag "Max number of tagged entries"))))) (defcustom org-agenda-max-effort nil @@ -2663,8 +2701,7 @@ to limit entries to in this type." (const agenda) (const todo) (const tags) - (const search) - (const timeline)) + (const search)) (integer :tag "Max number of minutes"))))) (defvar org-agenda-keep-restricted-file-list nil) @@ -2683,7 +2720,6 @@ T Call `org-todo-list' to display the global todo list, select only m Call `org-tags-view' to display headlines with tags matching a condition (the user is prompted for the condition). M Like `m', but select only TODO entries, no ordinary headlines. -L Create a timeline for the current buffer. e Export views to associated files. s Search entries for keywords. S Search entries for keywords, only with TODO keywords. @@ -2846,12 +2882,6 @@ Pressing `<' twice means to restrict to the current subtree or region (copy-sequence note)) nil 'face 'org-warning))))))) t t)) - ((equal org-keys "L") - (unless (derived-mode-p 'org-mode) - (user-error "This is not an Org file")) - (unless restriction - (put 'org-agenda-files 'org-restrict (list bfn)) - (org-call-with-arg 'org-timeline arg))) ((equal org-keys "#") (call-interactively 'org-agenda-list-stuck-projects)) ((equal org-keys "/") (call-interactively 'org-occur-in-agenda-files)) ((equal org-keys "!") (customize-variable 'org-stuck-projects)) @@ -2901,15 +2931,15 @@ Agenda views are separated by `org-agenda-block-separator'." (erase-buffer) (insert (eval-when-compile (let ((header - "Press key for an agenda command: < Buffer, subtree/region restriction --------------------------------- > Remove restriction -a Agenda for current week or day e Export agenda views -t List of all TODO entries T Entries with special TODO kwd -m Match a TAGS/PROP/TODO query M Like m, but only TODO entries -s Search for keywords S Like s, but only TODO entries -L Timeline for current buffer # List stuck projects (!=configure) -/ Multi-occur C Configure custom agenda commands -? Find :FLAGGED: entries * Toggle sticky agenda views + "Press key for an agenda command: +-------------------------------- < Buffer, subtree/region restriction +a Agenda for current week or day > Remove restriction +t List of all TODO entries e Export agenda views +m Match a TAGS/PROP/TODO query T Entries with special TODO kwd +s Search for keywords M Like m, but only TODO entries +/ Multi-occur S Like s, but only TODO entries +? Find :FLAGGED: entries C Configure custom agenda commands +* Toggle sticky agenda views # List stuck projects (!=configure) ") (start 0)) (while (string-match @@ -3344,6 +3374,7 @@ the agenda to write." (save-window-excursion (let ((bs (copy-sequence (buffer-string))) (extension (file-name-extension file)) + (default-directory (file-name-directory file)) beg content) (with-temp-buffer (rename-buffer org-agenda-write-buffer-name t) @@ -3374,7 +3405,8 @@ the agenda to write." (kill-buffer (current-buffer)) (message "Org file written to %s" file))) ((member extension '("html" "htm")) - (require 'htmlize) + (or (require 'htmlize nil t) + (error "Please install htmlize from https://github.com/hniksic/emacs-htmlize")) (set-buffer (htmlize-buffer (current-buffer))) (when org-agenda-export-html-style ;; replace