source-code-chapter.texi is just reference.org with level 1 headings
replaced with @section, and level 2 headings replaced with
@subsection, and with a top level @chapter node. This file is included
in org.texi with an @include line for now.
* lisp/org.el (org-ctrl-k-protect-subtree): New option.
(org-kill-line): Protect hidden subtrees if the user wants it.
* doc/org.texi (Headlines): Mention the special behavior of C-k
in headlines.
Scott Otterson writes:
> For what must be the dozenth time, I've just accidentally deleted a
> large tree by typing C-k while in a headline.
>
> This is really easy to do because emacs users have "C-k deletes to the
> end of the line" worn deeply into their neural pathways -- it's so
> automatic for me that the keystroke is close to subconscious. A
> mistaken C-k is especially hard to detect because org-mode displays
> the result exactly like what your subconscious expects, that is, a
> collapsed headline is deleted to the end -- and the tree underneath is
> wiped out with no noticeable warning.
>
> Feature request: add an option preventing tree deletion with C-k
> without user confirmation. Actually, I'd like an option to prevent it
> period.
>
> If this option is already in there, then you're encouraged to tell me
> to RTFM. But then also please tell me where it is, because I can't
> find it.
Carsten replies
> This is now possible due to the variable
> `org-ctrl-k-protect-subtree'. But I predict that you are going to set
> it to nil again soon :D
* doc/org.texi (Subscripts and superscripts): Document that `C-c C-x \'
will also format sub and superscripts.
* doc/orgcard.tex: Document that `C-c C-x \'
will also format sub and superscripts.
* lisp/org.el (org-use-sub-superscripts):
(org-pretty-entities-include-sub-superscripts): Move here from
org-exp.el.
(org-set-regexps-and-options): Parse subscript option and set
`org-use-sub-superscripts' as a local variable.
(org-match-sexp-depth):
(org-create-multibrace-regexp):
(org-match-substring-regexp):
(org-match-substring-with-braces-regexp): Moved here from org-exp.el
(org-set-font-lock-defaults): Call `org-raise-scripts'.
(org-remove-font-lock-display-properties): New function.
(org-unfontify-region): Call
`org-remove-font-lock-display-properties'.
(org-script-display): New constant.
(org-raise-scripts): New function.
When turning on entity display with `C-c C-x \', sub- and superscripts
will also be displayed in a smaller font, and raised/lowered.
* doc/org.texi (Plain lists): Document
`org-list-demote-modify-bullet'.
* lisp/org-list.el (org-list-demote-modify-bullet): Improve docstring
by showing an example.
This change was triggered by a request by Livin Stephen Sharma.
* org-clock.el (org-dblock-write:clocktable): Return total time.
(org-clocktable-steps): Skip step when time is zero and the
:stepskip0 property is set.
Rainer Stengele writes:
> Creating clocktables for each day of a month is an excellent feature
> in org! Problem for me is that many resulting tables have a total
> time of 0:00. The problem is not really the zero time I spent but the
> appearance of the tables with zero total time.
>
> Is there a possibility to skip getting such tables? Rational: I do
> not need to show my boss or customer days where I spent 0:00 time on
> the project.
Now you can set :stepskip0 to achieve this.
Adam Elliott writes:
> I have attached a git patch against master that implements a new
> parameter to clock tables, "tags". This parameter is a tags-query as a
> string and is used to filter the headlines which are consulted when
> building the clock table.
>
> In my search of the archives to see if this feature already existed, I
> found a reference here:
> http://article.gmane.org/gmane.emacs.orgmode/17304
> suggesting it was difficult. The patch is not so large, though, so
> perhaps I am missing something.
>
> My rationale in implementing this feature was to keep track of the
> occasional task item that is not billable, yet still makes sense to
> include in the overall project structure. Of course I could just avoid
> clocking the task item, or manually delete clock lines before generating
> a report, but this feature reduces the chance for error; no doubt there
> are other workflows enabled with this feature as well. I don't make
> significant use of tags myself, but I know many do.
>
> In order to maintain a sensible report, headlines that don't match the
> tag filter may be included if they have descendants that do. Any time
> clocked directly on non-matching headlines, however, is excluded.
>
> Specifying even a simple filter noticeably slows down clock table
> generation for non-toy reports, particularly for clock table reports
> with :step. If there is no filter, though, there is no degradation in
> performance.
>
> Tag filter syntax is the standard one, as described at:
> http://orgmode.org/manual/Matching-tags-and-properties.html
> Only tags are considered at the moment, although I suspect querying
> against all properties would be possible (if even slower).
>
> Examples:
>
> * development
> CLOCK: => 1:00
> *** task 1
> CLOCK: => 1:00
> *** task 2 :must:
> ***** task 2a
> CLOCK: => 1:00
> ***** task 2b :mustnot:
> CLOCK: => 1:00
>
> Note I am using an unconventional but legal(ish) clock format for
> brevity. Clock tables are also pruned to only relevant lines.
>
> [1] #+BEGIN: clocktable
> | | *Total time* | *4:00* | | |
> |---+--------------+--------+------+------|
> | 1 | development | 4:00 | | |
> | 2 | task 1 | | 1:00 | |
> | 2 | task 2 | | 2:00 | |
> | 3 | task 2a | | | 1:00 |
> | 3 | task 2b | | | 1:00 |
>
> [2] #+BEGIN: clocktable :tags "must"
> | | *Total time* | *2:00* | | |
> |---+--------------+--------+------+------|
> | 1 | development | 2:00 | | |
> | 2 | task 2 | | 2:00 | |
> | 3 | task 2a | | | 1:00 |
> | 3 | task 2b | | | 1:00 |
>
> [3] #+BEGIN: clocktable :tags "-mustnot"
> | | *Total time* | *3:00* | | |
> |---+--------------+--------+------+------|
> | 1 | development | 3:00 | | |
> | 2 | task 1 | | 1:00 | |
> | 2 | task 2 | | 1:00 | |
> | 3 | task 2a | | | 1:00 |
>
> [4] #+BEGIN: clocktable :tags "must-mustnot"
> | | *Total time* | *1:00* | | |
> |---+--------------+--------+------+------|
> | 1 | development | 1:00 | | |
> | 2 | task 2 | | 1:00 | |
> | 3 | task 2a | | | 1:00 |
>
> [5] #+BEGIN: clocktable :tags "must+mustnot"
> | | *Total time* | *1:00* | | |
> |---+--------------+--------+------+------|
> | 1 | development | 1:00 | | |
> | 2 | task 2 | | 1:00 | |
> | 3 | task 2b | | | 1:00 |
>
> As you can see, in examples 2, 4, and 5, the time clocked on
> "development" itself is being removed. Example 2 illustrates the effect
> of tag inheritance.
>
> Adam
This behavior is now parallel to the treatment of outline nodes.
This commit also introduces another change. When an outline node or a
plain list item is folded by outline and contains hidden children,
M-left/right will refuse to act on this item. You must either open
the tree, or use the subtree commands M-S-left and M-S-right.
Based on a patch by Matti De Craene, but significantly modified after
a discussion involving Bernt Hansen and others.
The target state can now be fixed locally with the REPEAT_TO_STATE
property, or globally with the variable `org-todo-repeat-to-state'.
This was a request by John Wiegley.
source-code-chapter.texi is just reference.org with level 1 headings
replaced with @section, and level 2 headings replaced with
@subsection, and with a top level @chapter node. This file is included
in org.texi with an @include line for now.
This new code will search #+INDEX lines in the buffer. For LaTeX, it
will simple convert these into LaTeX \index{} commands. For other
backends, it will copy thee entries to a new file, with extension
orgx. These files can then later be post-processed to create the index.
Dan Davison writes:
> Bug report
> ==========
> If I have this:
>
> A [[file:zz.org::#mytarget][link]] to a target with a custom ID
>
> and export it to HTML, I get
>
> A <a href="zz.html##mytarget">link</a> to a target with a custom ID
>
> which (in firefox on linux) links to the file but does not jump to the
> target. However, if I change the '##' to '#' then firefox jumps to the
> correct location. Is this an org bug?
>
> Very tentatively proposed patch
> ===============================
> I've investigated a bit (notes below), resulting in this proposed patch:
>
> --8<---------------cut here---------------start------------->8---
> diff --git a/lisp/org-html.el b/lisp/org-html.el
> index aa70408..5ee5b19 100644
> --- a/lisp/org-html.el
> +++ b/lisp/org-html.el
> @@ -1110,7 +1110,7 @@ lang=\"%s\" xml:lang=\"%s\">
> (abs-p (file-name-absolute-p filename))
> thefile file-is-image-p search)
> (save-match-data
> - (if (string-match "::\\(.*\\)" filename)
> + (if (string-match "::#?\\(.*\\)" filename)
> (setq search (match-string 1 filename)
> filename (replace-match "" t nil filename)))
> (setq valid
> --8<---------------cut here---------------end--------------->8---
>
> Doc patch
> =========
> The link above (file:zz.org::#mytarget) was created by C-c l on a
> heading with a CUSTOM_ID property. However, I couldn't see where in the
> manual links of this form are documented. Do we need to add this link
> type to section 4.7 "Search options in file links", e.g.
>
> --8<---------------cut here---------------start------------->8---
> diff --git a/doc/org.texi b/doc/org.texi
> index f49f056..c8cc1a5 100644
> --- a/doc/org.texi
> +++ b/doc/org.texi
> @@ -3116,6 +3116,7 @@ link, together with an explanation:
> [[file:~/code/main.c::255]]
> [[file:~/xx.org::My Target]]
> [[file:~/xx.org::*My Target]]
> +[[file:~/xx.org::#my-custom-id]]
> [[file:~/xx.org::/regexp/]]
> @end example
>
> @@ -3130,6 +3131,8 @@ link will become an HTML reference to the corresponding named anchor in
> the linked file.
> @item *My Target
> In an Org file, restrict search to headlines.
> +@item #my-custom-id
> +Link to a heading with a @code{CUSTOM_ID} property
> @item /regexp/
> Do a regular expression search for @code{regexp}. This uses the Emacs
> command @code{occur} to list all matches in a separate window. If the
> --8<---------------cut here---------------end--------------->8---
>
> Notes
> =====
> At line 1134 of org-html.el there is
>
> (setq thefile (concat thefile "#"
> (org-solidify-link-text
> (org-link-unescape search)))))
>
> during evaluation of which 'search is bound to "#mytarget", which
> suggested that the problem might be in the regexp parsing creating
> 'search.
This support was totally broken. It works now again. Unfortunately
it is not possible to edit the table directly in the org-mode buffer
anymore - to edit such a table, you have to use C-c '
This patch implements reading American dates, like
2/5/3 --> 2003-02-05
2/5 --> ????-02-05
Is also fixes a bug that would force the current year when reading a
date like 2/5 (American) or 2-5 (ISO), and in this way would prevent
`org-read-date-prefer-future' to do its job. This bug was reported by
Lukasz Stelmach.
This can help to get out of an inconsistent state produce for example
by viewing from the agenda. Reported by Matt Lundin:
> I'd like to report a minor issue with org-agenda-goto and inline tasks.
> Let's say one has the following file:
>
> --8<---------------cut here---------------start------------->8---
> * Here is an entry.
> Blah blah blah blah.
> *************** Here is an inline task.
> *************** END
> Blah blah blah blah blah.
> *************** TODO Here is a second inline task.
> *************** END
> Blah blah blah blah blah.
> *************** Here is a third inline task
> *************** END
> Blah blah blah blah blah.
> --8<---------------cut here---------------end--------------->8---
>
> Let's say one also has the following settings:
>
> --8<---------------cut here---------------start------------->8---
> (setq org-show-hierarchy-above t)
> (setq org-show-siblings '((default . nil) (isearch . t) (agenda . t)))
> (setq org-show-entry-below '((default . nil) (isearch . t) (agenda . t)))
> --8<---------------cut here---------------end--------------->8---
>
> If 1) one tries to jump to the TODO from the agenda and 2) the entry is
> currently folded, org-show-context reveals only the headlines. E.g.,
>
> --8<---------------cut here---------------start------------->8---
> * Here is an entry.
> *************** Here is an inline task.
> *************** END...
> *************** TODO Here is a second inline task.
> *************** END...
> *************** Here is a third inline task
> *************** END...
> --8<---------------cut here---------------end--------------->8---
>
> Invoking org-cycle on the END headline does nothing, since all headlines
> deeper than org-inlinetask-min-level are exempted from cycling. As a
> result, the only way to reveal the text in the entry is to cycle the
> parent twice (first to close, then to reveal).
Add a variable org-complete-tags-always-offer-all-agenda-tags, which makes org
complete all tags from all agenda files if non-nil. Usually, setting it
locally to t in org-remember buffers is most convenient.
Rick Moynihan writes:
> I'm wondering if anyone logs rescheduled tasks with org-mode... As I
> find myself sometimes scheduling tasks for a future date, but then on
> the day not having the capacity to do them. In these situations I
> just reschedule them, but it'd be nice to record the dates for which
> an item was originally scheduled in the LOGBOOK.
>
> Has anyone configured org-mode to do this? lognotedone only appears to
> log state changes (rather than schedule/deadline changes).
The following keys now do archiving
C-c C-x C-a archive using the command specified in
`org-archive-default-command'
This variable is by default set to `org-archive-subtree', which means
arching to the archive file.
The three specific archiving commands are available through
C-c C-x C-s archive to archive file
C-c C-x a toggle the archive tag
C-c C-x A move to archive sibling
These bindings work the same in an Org file, and in the agenda.
In addition:
- In the agenda you can also use `a' to call the default archiving
command, but you need to confirm the command with `y' so that this
cannot easily happen by accident.
- For backward compatibility, `C-c $' in an org-mode file, and `$' in
the agenda buffer continue to archive to archive file.
Now the recommendation is to use clock persistence only for the
history, and to use John's code for resolving a clock that has been
idle (either because the user stopped working or exited Emacs).
org-habit.el: New file, which implements code to build a "habit
consistency graph".
org-agenda.el (org-agenda-get-deadlines)
(org-agenda-get-scheduled): Display consistency graphs when outputting
habits into the agenda. The graphs are always relative to the current
time.
(org-format-agenda-item): Added new parameter `habitp', which indicates
whether we are formatting a habit or not. Do not display "extra"
leading information if habitp is true.
(org-agenda-auto-exclude-function): New customization variable for
allowing the user to create an "auto exclusion" filter for doing
context-aware auto tag filtering.
(org-agenda-filter-by-tag): Changes to support the use of
`org-agenda-auto-exclude-function'. See the new manual addition,.
See the new manual section on "Resolving idle time".
(org-clock-resolve-clock): If keeping or subtracting time results in a
clock out at a time in the past, and if the resolution occurred due to
idleness or invoking `M-x org-resolve-clocks', remember that past moment
in time. On the next clock in, the user will be prompted to see if they
want to back-date their new clock to then.
(org-clock-resolve): Do not jump the user to the location of a dangling
clock if the resolution is occuring due to an idle timeout. In that
case there is typically only one dangling clock, the active one, and
there is no value gained by shuffling their windows around to show it to
them. Being prompted to resolve an idle clock should be as inobtrusive
as possible.
(org-resolve-clocks-if-idle): New function that resolves only the
currently active clock if the user has exceeded the time returned by
`org-user-idle-seconds', based on the value of `org-clock-idle-time'.
(org-clock-in): If, after resolving clocks,
(org-clock-out): Cancel the `org-clock-idle-timer' on clock out.
This file should be with the other org files, and not in the staging
area. Also, when file names in mobileorg.org are interpreted, this
should be relative to org-directory. So we also require now that the
user set this variable.
The default in search view is not that the search expression is
searched for as a substring, i.e. the different words must occur in
direct sequence. The old way is only used it the first word in
the search string is preceded by a plus or a minus.
This was, more-or-less, requested by John Wiegley.
The reorganizes parts of the manual. The Archiving stuff has been
moved into the new chapter "Capture-Refile-Archive". Also, there is a
new chapter "Markup" to contains both the markup rules (moved there
from the Export chapter) and the embedded LaTeX stuff.
PT writes:
> Currently, I'm using Google Calendar and it's quick add syntax is very
> convenient:
>
> http://www.google.com/support/calendar/bin/answer.py?hl=en&answer=36604#text
>
>
> Of course, Org has similar capabilites, but I found one thing which
> google calendar does better: if it's 4pm and I add an event for 8am
> then GCal schedules it for 8am tomorrow.
>
> Org, on the the other hand, schedules it for 8am today even if that
> time is already passed.
>
> I never add past events and I think it's quite atypical. Shouldn't be
> an option similar to org-read-date-prefer-future for times too, so
> that timestamps also prefer the future when no date given?
This is now possible, but it is not the default. You need to set
(setq org-read-date-prefer-future 'time)
The new variable org-mobile-files can now be configured to include
non-agenda files into the staging area for MobileOrg. Furthermore,
files that are located in a subdirectory of `org-directory' will also
end up in a sub-directory in the staging area.
Peter Westlake writes:
> Could I request this as a small feature enhancement, please?
> Commands like org-refile have an agenda equivalent so that
> the same keys work in the agenda, and it would be very nice
> to be able to store a link to an item that way as well.
The width and alignment in table columns can be set with a cookie like
"<10>" or "<r>" or "<r10>". In order to keep Org from exporting such
lines, the first column of a line can contain only "/". However, for
convenience, this commit implements a special case: If the entire row
contains only sch markers, the line will automatically be discarded
during export.
The new keys are b and f. This used to be on the cursor keys, but
they do now again do cursor motion.
This is a significant change in the UI, I hope this will not cause too
many problems.
A relative row reference like @-1 in a table may now reach across a
horizontal separator line. I hope this will not break any important
tables out there, but I think it is the right thing to do.
The original reason for not-crossing was to implement running
averages of one column in the next. This can now be done using field
formulas near the beginning and end of the column, and a column
formula for the central part.
See the variable `org-table-relative-ref-may-cross-hline' for more
details.
Using :timetamp t as an option in a clock report now allows
insertion of the timestamp for the clocked entry. Timestamps
are searched for in this order: SCHEDULING, TIMESTAMP, DEADLINE
and TIMESTAMP_IA.
Allow whitespace in code references. Allow the -r switch to remove the
references in the source code even when the lines are not numbered: the
labels can be explicit enough. Note that "-r -k" is the same than no
switch - as expected.
Thanks to Ulf Stegemann for bring this up.
This hook is called in org-clock-in earlier than the existing
org-clock-in-hook. This is useful for functions that need to
modify the Effort property, for example.
When changing the publishing setup, old timestamp files can be left
behind. Forcing publishing of all projects with `C-u C-c C-e E'
will remove all existing timestamp files.
Many different people want to set many different variables in a
buffer-local way for export. This cannot be done with file variables,
because the Org buffer is not current while the exporter is running.
Lots of variables can be set with the #+OPTIONS lines, but finding
abbreviations goes only so far.
Therefore we have now a general mechanism that can be used to bind
variables during export operations.
a line like: #+BIND: variable value
will bind the variable to value. For example,
the line
>> #+OPTIONS: toc:nil
can now equivalently be written as
>> #+BIND: org-export-with-toc nil
Customize the new variable org-footnote-auto-adjust or use the STARTUP
option fnadjust to get automatic renumbering and sorting of footnotes
after each insertion/deletion.
Agenda bulk commands on marked entries now can also set the scheduling
date or a deadline. Normally, all entries will be set to the
specified date. However, when writing the change as "++5d" or "++2w",
then each time stamp will independently be shifted by that amount.
TAB now cycles visibility in plain lists if the cursor is in a plain
list. This corresponds now to the new default value `t' of
`org-cycle-include-plain-lists'. If you want to treat plain list
items as part of the outline hierarchy during cycling of outline
headings (this is what a `t' value used to mean), set this variable to
`integrate'.
This commit implements refiling directly from the agenda.
It also implements a mechanism for selecting a number of entries in
the agenda and then executing a command on all of them. Possible
actions include archive, refile, todo state setting, and more.
Michael Brand writes:
> 2) One could like to have configurable left/right alignment, even
> combinable with column width, e. g.
>
> | <l10> | <r> |
> | 3.14 | 0x10 |
> | 3.141592=> | 0x32 0x10 |
Good idea, I would say.
Clicking on the clock in the mode line now pops up a menu with
clocking options.
A new command `C-c C-x C-e' allows to set or change the effort
estimate of the task currently being clocked. This is mainly useful
when using an alert notification when the task should be finished.
Based on a patch by Konstantin Antipin.
This commit changes which time is shown in the mode line while
clocking. Normally this will now be the total time ever clocked on
this task and its children.
However, when the task is a repeating one, only the time since the
last reset of the task will be shown. The time of the last reset is
now recorded in a LAST_REPEAT property.
You can also set the CLOCK_MODELINE_TOTAL property to the value
"current" to only show the current clocking instance. Or it may be
the value "today", to only add up the time spent today on this task.
Other possible values are "repeat", "all", or "auto".
Finally, you can set your default for this property with
`org-clock-modeline-total'.
This commit introduces two new variables:
- org-treat-insert-todo-heading-as-state-change
Default is nil. When set to t, adding a new TODO item will be done
by adding an item and the executing an "official" state change which
potentially will trigger state logging.
- org-treat-S-cursor-todo-seletion-as-state-change
Default is t. When set to nil, selecting a TODO state with
S-left/right will not trigger logging, only selecting a new state
with `C-c C-t'. I actually like this a lot and would even consider
making this the default.
Mikael Fornius writes:
> This is my suggestion of an implementation of min/mean/max computation
> in columnview summaries. If you like it feel free to use it.
>
> New operators: {min}, {max} and {mean} possibly prefixed with : for use
> with timevalues.
>
> Example from my running exercise diary:
>
> #+COLUMNS: %DISTANCE{+;%.1f} %HEARTRATE{mean;%.1f} %SPEED{:min} %CALORIES{+}
>
> Gives a colview with summaries:
>
> total distance, mean heartrate, fastest speed (min/km) and total
> calories.
>
> I have tested it on emacs-23 and it works well for me now, also with the
> interactive colview functions.
>
> But you never know really. ;-) Anyway, there should not be any emacs-23
> specific elisp code added afik.
>
> (Because I do not use xemacs I have not tested it with xemacs but the
> small changes I made should be compitable to both xemacs and emacs. I
> would appreciate if someone on this list who uses xemacs will give it a
> try for me. Thanks!)
>
> (This fix also opens up for using user defined lisp functions to
> calculate colview summaries, but I am not sure if that is something
> useful. Like this:
>
> (defun std (&rest values)
> "Compute standard deviation."
> ...)
>
> #+COLUMNS: %DATA{eval:std}
>
> If someone finds this attractive it would now be easy to implement as well.)
>
Hsiu-Khuern Tang writes:
> Hi Carsten,
>
> You recently changed org-edit-src-code to use a separate buffer
> instead of an indirect buffer. One side effect of this is that I
> can no longer edit several code examples at the same time:
> opening the second buffer will silently discard any changes made
> in the first. I would prefer this behavior: when opening the
> second edit source buffer, write any changes in the first buffer
> to the originating Org buffer (but don't save it, of course).
>
> Another approach is to use different buffer names.
The better approach is clearly to allow several buffers, now
implemented with this commit.
There is now a new export function, `org-export-as-org', which
basically creates a copy of the Org file with things like archived
trees, commented trees, and trees deselected by export tags,
stripped.
Tom Dye
Eric Schulte
Dan Davison
Bastien Guerry
Christian Egli
Carsten Dominik
Tassilo Horn
Jan Böcker
Bernt Hansen
James TD Smith
John Wiegley