Merge upstream Org (from commit 488eea)

doc/misc/ChangeLog

+2012-12-12  Bastien Guerry  <bzg@gnu.org>
+
+	* org.texi (Summary, Code block specific header arguments)
+	(Code block specific header arguments)
+	(Header arguments in function calls, var, noweb)
+	(Results of evaluation, Code evaluation security): Small
+	reformatting: add a blank line before some example.
+
+	* org.texi (System-wide header arguments)
+	(Header arguments in Org mode properties, Conflicts)
+	(Dynamic blocks, Using the mapping API): Fix indendation of
+	Elisp code examples.
+
+	* org.texi (Comment lines): Fix description of the comment syntax.
+
+	* org.texi (Installation): Mention "make test" in the correct
+	section.
+
 2012-12-02  Michael Albinus  <michael.albinus@gmx.de>
 
 	* tramp.texi (Top, Obtaining Tramp): Replace CVS by Git.

doc/misc/org.texi

@@ -834,7 +834,6 @@ ends, for example:
 @r{@bullet{} an environment for literate programming}
 @end example
-
 @cindex FAQ
 There is a website for Org which provides links to the newest
 version of Org, as well as additional information, frequently asked
@@ -879,8 +878,6 @@ Lisp and Info files will be installed.  If the Emacs binary is not in your
 path, give the full path to the executable.  Avoid spaces in any path names.
 @item Run @code{make config}
 again to check the configuration.
-@item Optionally run @code{make test}
-to build Org mode and then run the full testsuite.
 @item Run @code{make install} or @code{sudo make install}
 to build and install Org mode on your system.
 @end itemize
@@ -903,6 +900,8 @@ Emacs binary is not in your path, you must give the full path to the
 executable.  Avoid spaces in any path names.
 @item Run @code{make config}
 to check the configuration.
+@item Optionally run @code{make test}
+to build Org mode and then run the full testsuite.
 @item Run @code{make update2} or @code{make up2}
 to update the Git repository and build and install Org mode.  The latter
 invocation runs the complete test suite before installation and installs only
@@ -947,7 +946,7 @@ description on Worg}.
 Installing Info files is system dependent, because of differences in the
 @file{install-info} program.  The Info documentation is installed together
 with the rest of Org mode.  If you don't install Org mode, it is possible to
-install the Info documentation separately (you need to have
+install the Info documentation seperately (you need to have
 install-info@footnote{The output from install-info (if any) is system
 dependent.  In particular Debian and its derivatives use two different
 versions of install-info and you may see the message:
@@ -9222,11 +9221,11 @@ a horizontal line (@samp{<hr/>} in HTML and @code{\hrule} in @LaTeX{}).
 @cindex exporting, not
 @cindex #+BEGIN_COMMENT
-Lines starting with zero or more whitespace characters followed by @samp{#}
-are treated as comments and will never be exported.  Also entire subtrees
-starting with the word @samp{COMMENT} will never be exported.  Finally,
-regions surrounded by @samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will
-not be exported.
+Lines starting with zero or more whitespace characters followed by one
+@samp{#} and a whitespace are treated as comments and will never be exported.
+Also entire subtrees starting with the word @samp{COMMENT} will never be
+exported.  Finally, regions surrounded by @samp{#+BEGIN_COMMENT}
+... @samp{#+END_COMMENT} will not be exported.
 @table @kbd
 @kindex C-c ;
@@ -13155,8 +13154,8 @@ blocks.
 @lisp
 (setq org-babel-default-header-args
-(cons '(:noweb . "yes")
-(assq-delete-all :noweb org-babel-default-header-args)))
+      (cons '(:noweb . "yes")
+	    (assq-delete-all :noweb org-babel-default-header-args)))
 @end lisp
 @node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
@@ -13201,9 +13200,9 @@ blocks in the subtree rooted at the following heading:
 @example
 * outline header
-:PROPERTIES:
-:cache:    yes
-:END:
+  :PROPERTIES:
+  :cache:    yes
+  :END:
 @end example
 @kindex C-c C-x p
@@ -13247,6 +13246,7 @@ Code block header arguments can span multiple lines using @code{#+HEADER:} or
 @cindex #+HEADERS:
 Multi-line header arguments on an un-named code block:
+
 @example
  #+HEADERS: :var data1=1
  #+BEGIN_SRC emacs-lisp :var data2=2
@@ -13258,6 +13258,7 @@ Multi-line header arguments on an un-named code block:
 @end example
 Multi-line header arguments on a named code block:
+
 @example
    #+NAME: named-block
    #+HEADER: :var data=2
@@ -13280,12 +13281,14 @@ blocks}.
 The following will apply the @code{:exports results} header argument to the
 evaluation of the @code{#+CALL:} line.
+
 @example
 #+CALL: factorial(n=5) :exports results
 @end example
 The following will apply the @code{:session special} header argument to the
 evaluation of the @code{factorial} code block.
+
 @example
 #+CALL: factorial[:session special](n=5)
 @end example
@@ -13366,6 +13369,7 @@ Here are examples of passing values by reference:
 @item table
 an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line
+
 @example
 #+TBLNAME: example-table
 | 1 |
@@ -13948,7 +13952,6 @@ This code block:
 -- <<example>>
 @end example
-
 expands to:
 @example
@@ -14331,6 +14334,7 @@ process.  For example, compare the following two blocks:
 @end example
 In non-session mode, the `2' is not printed and does not appear.
+
 @example
 #+BEGIN_SRC python :results output :session
  print "hello"
@@ -14705,6 +14709,7 @@ ask and nil not to ask.
 For example, here is how to execute "ditaa" code (which is considered safe)
 without asking:
+
 @example
 (defun my-org-confirm-babel-evaluate (lang body)
   (not (string= lang "ditaa")))  ; don't ask for ditaa
@@ -14806,7 +14811,7 @@ buffer, most useful for specifying the allowed values of a property.
 @item #+SETUPFILE: file
 This line defines a file that holds more in-buffer setup.  Normally this is
 entirely ignored.  Only when the buffer is parsed for option-setting lines
-(i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
+(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
 settings line, or when exporting), then the contents of this file are parsed
 as if they had been included in the buffer.  In particular, the file can be
 any other Org mode file with internal setup.  You can visit the file the
@@ -15168,7 +15173,7 @@ example using the color @code{grey90} on a white background.
 Things become cleaner still if you skip all the even levels and use only odd
 levels 1, 3, 5..., effectively adding two stars to go from one outline level
 to the next@footnote{When you need to specify a level for a property search
-or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}.  In this
+or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}.  In this
 way we get the outline view shown at the beginning of this section.  In order
 to make the structure editing and export commands handle this convention
 correctly, configure the variable @code{org-odd-levels-only}, or set this on
@@ -15259,7 +15264,7 @@ names for natural constants or units.  Instead of defining your own
 constants in the variable @code{org-table-formula-constants}, install
 the @file{constants} package which defines a large number of constants
 and units, and lets you use unit prefixes like @samp{M} for
-@samp{Mega}, etc.  You will need version 2.0 of this package, available
+@samp{Mega}, etc@.  You will need version 2.0 of this package, available
 at @url{http://www.astro.uva.nl/~dominik/Tools}.  Org checks for
 the function @code{constants-get}, which has to be autoloaded in your
 setup.  See the installation instructions in the file
@@ -15401,7 +15406,7 @@ function:
 @lisp
 (defun yas/org-very-safe-expand ()
-       (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
+  (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
 @end lisp
 Then, tell Org mode what to do with the new function:
@@ -15409,10 +15414,10 @@ Then, tell Org mode what to do with the new function:
 @lisp
 (add-hook 'org-mode-hook
           (lambda ()
-              (make-variable-buffer-local 'yas/trigger-key)
-              (setq yas/trigger-key [tab])
-              (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
-              (define-key yas/keymap [tab] 'yas/next-field)))
+	    (make-variable-buffer-local 'yas/trigger-key)
+	    (setq yas/trigger-key [tab])
+	    (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
+	    (define-key yas/keymap [tab] 'yas/next-field)))
 @end lisp
 @item @file{windmove.el} by Hovav Shacham
@@ -16053,9 +16058,9 @@ The corresponding block writer function could look like this:
 @lisp
 (defun org-dblock-write:block-update-time (params)
-   (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
-     (insert "Last block update at: "
-             (format-time-string fmt (current-time)))))
+  (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
+    (insert "Last block update at: "
+	    (format-time-string fmt (current-time)))))
 @end lisp
 If you want to make sure that all dynamic blocks are always up-to-date,
@@ -16450,8 +16455,8 @@ Entries in comment trees and in archive trees will be ignored.
 @lisp
 (org-map-entries
-   '(org-todo "UPCOMING")
-   "+TOMORROW" 'file 'archive 'comment)
+ '(org-todo "UPCOMING")
+ "+TOMORROW" 'file 'archive 'comment)
 @end lisp
 The following example counts the number of entries with TODO keyword
@@ -16693,7 +16698,7 @@ on @file{org-element.el} and @file{org-export.el} has been outstanding, and
 opened the doors for many new ideas and features.
 @item Jambunathan K
-Jambunathan contributed the ODT exporter, definitely a killer feature of
+Jambunathan contributed the ODT exporter, definitly a killer feature of
 Org mode.  He also contributed the new HTML exporter, which is another core
 feature of Org.  Here too, I knew I could rely on him to fix bugs in these
 areas and to patiently explain the users what was the problems and solutions.
@@ -16701,7 +16706,7 @@ areas and to patiently explain the users what was the problems and solutions.
 @item Achim Gratz
 Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
 into a flexible and conceptually clean process.  He patiently coped with the
-many hiccups that such a change can create for users.
+many hicups that such a change can create for users.
 @item Nick Dokos
 The Org mode mailing list would not be such a nice place without Nick, who

lisp/org/ChangeLog

+2012-12-12  Bastien Guerry  <bzg@gnu.org>
+
+	* org-latex.el (org-export-latex-links): Escape raw path when
+	exporting links to files.
+
+	* org-src.el (org-src-native-tab-command-maybe): Fix bug: the
+	S-TAB key should not trigger a native TAB command.
+
+	* org.el (org-open-at-point): Allow to open any link within
+	footnotes definition, not only bracket links.
+
+	* org.el (org-sort-entries): Bugfix: keep track of the clock
+	marker when sorting entries.  Enhance the docstring.
+
+	* org-clock.el (org-clock-out): Use `user-error' when the user
+	tries to clock out while there is no running clock.
+
+	* org-table.el (org-table-sort-lines): Ensure coordinates are
+	correctly displayed when sorting.
+
+	* org.el (org-do-sort): Enhance prompt.
+
+	* org-agenda.el (org-agenda-finalize): Also activate plain links.
+
+	* org-timer.el (org-timer-stop): Add message.
+
+	* org-agenda.el (org-agenda-schedule, org-agenda-deadline): Fix
+	redundant messages.
+
+	* org-agenda.el (org-agenda-finalize): Fix clock highlighting.
+
+	* org.el (org-additional-option-like-keywords): Add "INDEX:".
+
+	* org-install.el: Enhance warning.
+
+2012-12-12  Erik Hetzner  <egh@e6h.org>  (tiny change)
+
+	* org.el (org-log-into-drawer): Honor the nil value for the
+	:LOG_INTO_DRAWER: property.
+
+2012-12-12  Le Wang  <l26wang@gmail.com>  (tiny change)
+
+	* org-src.el (org-edit-src-exit): Fix editing source section with
+	blank lines.
+
+2012-12-12  Le Wang  <le.wang@agworld.com.au>
+
+	* org-src.el (org-edit-src-code): Use marker with insertion type
+	t to track end and remove hack requiring delete from beg to (1- end).
+
+2012-12-12  Nicolas Goaziou  <n.goaziou@gmail.com>
+
+	* org-element.el (org-element-context): When point is between two
+	objects, be sure to return the second one.
+
+	* org-list.el (org-list-separating-blank-lines-number): When
+	computing number of blank lines separating items, also count those
+	in unparsed blocks, like example blocks.
+
+	* org.el (org-end-of-line): When visual line mode is on, really
+	move by visual lines.  Small refactoring.
+
+	* org.el (org-end-of-line): On a hidden block make sure to
+	delegate motion to `end-of-line' instead of `move-end-of-line' in
+	order to stay on the current line.
+
+2012-12-12  Rafael Laboissiere  <rafael@laboissiere.net>  (tiny change)
+
+	* org-bibtex.el: In the documentation section of the file, fix the
+	broken URL to Andrew Roberts' document on BibTeX entries.
+
+	* org-remember.el (org-remember-handler): Correctly strip the
+	comment lines in the temporary buffer *Remember* when handling a
+	remember note.
+
+	* org-remember.el (org-remember-apply-template): Start the
+	commented lines in the Remember temporary buffer with the
+	appropriate characters.
+
+2012-12-12  Toby S. Cubitt  <tsc25@cantab.net>
+
+	* org.el (org-beginning-of-line): Check `visual-line-mode' instead
+	of `line-visual-mode' to determine whether to move by visual
+	lines.
+
+	* org.el (org-kill-line): Use the `org-bound-and-true-p' macro.
+
 2012-10-26  Achim Gratz  <stromeko@stromeko.de>
 	* ob-ditaa.el: Needs to (require 'org-compat) for

lisp/org/org-agenda.el

@@ -3517,6 +3517,9 @@ generating a new one."
 	(while (org-activate-bracket-links (point-max))
 	  (add-text-properties (match-beginning 0) (match-end 0)
 			       '(face org-link)))
+	(while (org-activate-plain-links (point-max))
+	  (add-text-properties (match-beginning 0) (match-end 0)
+			       '(face org-link)))
 	(org-agenda-align-tags)
 	(unless org-agenda-with-colors
 	  (remove-text-properties (point-min) (point-max) '(face nil))))
@@ -3531,7 +3534,11 @@ generating a new one."
 	(org-agenda-fontify-priorities))
       (when (and org-agenda-dim-blocked-tasks org-blocker-hook)
 	(org-agenda-dim-blocked-tasks))
-      (org-agenda-mark-clocking-task)
+      ;; We need to widen when `org-agenda-finalize' is called from
+      ;; `org-agenda-change-all-lines' (e.g. in `org-agenda-clock-in')
+      (save-restriction
+      	(widen)
+	(org-agenda-mark-clocking-task))
       (when org-agenda-entry-text-mode
 	(org-agenda-entry-text-hide)
 	(org-agenda-entry-text-show))
@@ -8602,7 +8609,7 @@ ARG is passed through to `org-schedule'."
 	(goto-char pos)
 	(setq ts (org-schedule arg time)))
       (org-agenda-show-new-time marker ts "S"))
-    (message "Item scheduled for %s" ts)))
+    (message "%s" ts)))
 
 (defun org-agenda-deadline (arg &optional time)
   "Schedule the item at point.
@@ -8622,7 +8629,7 @@ ARG is passed through to `org-deadline'."
 	(goto-char pos)
 	(setq ts (org-deadline arg time)))
       (org-agenda-show-new-time marker ts "D"))
-    (message "Deadline for this item set to %s" ts)))
+    (message "%s" ts)))
 
 (defun org-agenda-clock-in (&optional arg)
   "Start the clock on the currently selected item."

lisp/org/org-bibtex.el

@@ -88,7 +88,7 @@
 ;;
 ;; - All Bibtex information is taken from the document compiled by
 ;;   Andrew Roberts from the Bibtex manual, available at
-;;   http://www.andy-roberts.net/misc/latex/sessions/bibtex/bibentries.pdf
+;;   http://www.andy-roberts.net/res/writing/latex/bibentries.pdf
 ;;
 ;;; History:
 ;;

lisp/org/org-clock.el

@@ -1447,7 +1447,7 @@ to, overriding the existing value of `org-clock-out-switch-to-state'."
 	    (delq 'org-mode-line-string global-mode-string))
       (setq frame-title-format org-frame-title-format-backup)
       (force-mode-line-update)
-      (if fail-quietly (throw 'exit t) (error "No active clock")))
+      (if fail-quietly (throw 'exit t) (user-error "No active clock")))
     (let ((org-clock-out-switch-to-state
 	   (if switch-to-state
 	       (completing-read "Switch to state: "

lisp/org/org-element.el

@@ -4316,18 +4316,22 @@ and :post-blank properties."
 				(funcall (intern (format "org-element-%s-parser"
 							 (car closest-cand))))))
 			(cbeg (org-element-property :contents-begin object))
-			(cend (org-element-property :contents-end object)))
+			(cend (org-element-property :contents-end object))
+			(obj-end (org-element-property :end object)))
 		   (cond
 		    ;; ORIGIN is after OBJECT, so skip it.
-		    ((< (org-element-property :end object) origin)
-		     (goto-char (org-element-property :end object)))
-		    ;; ORIGIN is within a non-recursive object or at an
-		    ;; object boundaries: Return that object.
+		    ((<= obj-end origin)
+		     (if (/= obj-end end) (goto-char obj-end)
+		       (throw 'exit
+			      (org-element-put-property
+			       object :parent parent))))
+		    ;; ORIGIN is within a non-recursive object or at
+		    ;; an object boundaries: Return that object.
 		    ((or (not cbeg) (> cbeg origin) (< cend origin))
 		     (throw 'exit
 			    (org-element-put-property object :parent parent)))
-		    ;; Otherwise, move within current object and restrict
-		    ;; search to the end of its contents.
+		    ;; Otherwise, move within current object and
+		    ;; restrict search to the end of its contents.
 		    (t (goto-char cbeg)
 		       (org-element-put-property object :parent parent)
 		       (setq parent object

lisp/org/org-latex.el

@@ -2291,14 +2291,13 @@ The conversion is made depending of STRING-BEFORE and STRING-AFTER."
 		    (concat type ":" raw-path))
 		   ((equal type "file")
 		    (if (and (org-file-image-p
-			      (expand-file-name
-			       raw-path)
+			      (expand-file-name (org-link-unescape raw-path))
 			      org-export-latex-inline-image-extensions)
-			     (or (get-text-property 0 'org-no-description
-						    raw-path)
+			     (or (get-text-property 0 'org-no-description raw-path)
 				 (equal desc full-raw-path)))
 			(setq imgp t)
-		      (progn (when (string-match "\\(.+\\)::.+" raw-path)
+		      (progn (setq raw-path (org-link-unescape raw-path))
+			     (when (string-match "\\(.+\\)::.+" raw-path)
 			       (setq raw-path (match-string 1 raw-path)))
 			     (if (file-exists-p raw-path)
 				 (concat type "://" (expand-file-name raw-path))

lisp/org/org-list.el

@@ -1230,7 +1230,9 @@ some heuristics to guess the result."
 	     ;; Are there blank lines inside the list so far?
 	     ((save-excursion
 		(goto-char (org-list-get-top-point struct))
-		(org-list-search-forward
+		;; Do not use `org-list-search-forward' so blank lines
+		;; in blocks can be counted in.
+		(re-search-forward
 		 "^[ \t]*$" (org-list-get-item-end-before-blank item struct) t))
 	      1)
 	     ;; Default choice: no blank line.

lisp/org/org-remember.el

@@ -472,12 +472,12 @@ to be run from that hook to function properly."
 	(erase-buffer)
 	(insert (substitute-command-keys
 		 (format
-		  "## %s  \"%s\" -> \"* %s\"
-## C-u C-c C-c  like C-c C-c, and immediately visit note at target location
-## C-0 C-c C-c  \"%s\" -> \"* %s\"
-## %s  to select file and header location interactively.
-## C-2 C-c C-c  as child (C-3: as sibling) of the currently clocked item
-## To switch templates, use `\\[org-remember]'.  To abort use `C-c C-k'.\n\n"
+		  "# %s  \"%s\" -> \"* %s\"
+# C-u C-c C-c  like C-c C-c, and immediately visit note at target location
+# C-0 C-c C-c  \"%s\" -> \"* %s\"
+# %s  to select file and header location interactively.
+# C-2 C-c C-c  as child (C-3: as sibling) of the currently clocked item
+# To switch templates, use `\\[org-remember]'.  To abort use `C-c C-k'.\n\n"
 		  (if org-remember-store-without-prompt "    C-c C-c" "    C-1 C-c C-c")
 		  (abbreviate-file-name (or file org-default-notes-file))
 		  (or headline "")
@@ -840,12 +840,12 @@ See also the variable `org-reverse-note-order'."
       (if (= end beg) (setq beg (1- beg)))
       (put-text-property beg end 'org-position-cursor t)))
   (goto-char (point-min))
-  (while (looking-at "^[ \t]*\n\\|^##.*\n")
+  (while (looking-at "^[ \t]*\n\\|^# .*\n")
     (replace-match ""))
   (when org-remember-delete-empty-lines-at-end
     (goto-char (point-max))