Install a better error message for the "Before first heading" error.

Org sometimes hits a "Before first heading" error.  This error happens
when `outline-back-to-heading' is called before the first heading in a
buffer.  In normal use, this is something easy to fix, because of
course you know where you are and you can identify the problem.

However, when Org scans many different buffers, for example to collect
agenda entries, you may not be able to tell easily where this error
happened.  This patch introduces a wrapper around
`outline-back-to-heading', with improving the error message by
spelling out buffer and location.

lisp/ChangeLog

@@ -1,5 +1,13 @@
 2008-11-13  Carsten Dominik  <carsten.dominik@gmail.com>
 
+	* org.el (org-up-heading-safe, org-forward-same-level): Always
+	call `org-back-to-heading' instead of `outline-back-to-heading'.
+	(org-back-to-heading): New wrapper around outline-back-to-heading,
+	with a useful error message telling where the error happened.
+
+	* org-list.el (org-update-checkbox-count): Always call
+	`org-back-to-heading' instead of `outline-back-to-heading'.
+
 	* org-exp.el (org-export-as-html): Make sure that each <img> tag
 	has an `alt' attribute, to ensure XHTML validation.
 

lisp/org-list.el

@@ -259,7 +259,7 @@ the whole buffer."
  (save-excursion
    (let* ((buffer-invisibility-spec (org-inhibit-invisibility)) ; Emacs 21
 	  (beg (condition-case nil
-		   (progn (outline-back-to-heading) (point))
+		   (progn (org-back-to-heading) (point))
 		 (error (point-min))))
 	  (end (move-marker (make-marker)
 			    (progn (outline-next-heading) (point))))

lisp/org.el

@@ -14087,7 +14087,13 @@ plainly yank the text as it is.
 	(outline-invisible-p)
       (get-char-property (point) 'invisible))))
 
-(defalias 'org-back-to-heading 'outline-back-to-heading)
+(defun org-back-to-heading (invisible-ok)
+  "Call `outline-back-to-heading', but provide a better error message."
+  (condition-case nil
+      (outline-back-to-heading invisible-ok)
+    (error (error "Before first headline at position %d in buffer %s"
+		  (point) (current-buffer)))))
+
 (defalias 'org-on-heading-p 'outline-on-heading-p)
 (defalias 'org-at-heading-p 'outline-on-heading-p)
 (defun org-at-heading-or-item-p ()
@@ -14112,7 +14118,7 @@ headline found, or nil if no higher level is found."
   (let ((pos (point)) start-level level
 	(re (concat "^" outline-regexp)))
     (catch 'exit
-      (outline-back-to-heading t)
+      (org-back-to-heading t)
       (setq start-level (funcall outline-level))
       (if (equal start-level 1) (throw 'exit nil))
       (while (re-search-backward re nil t)
@@ -14188,7 +14194,7 @@ When ENTRY is non-nil, show the entire entry."
 Stop at the first and last subheadings of a superior heading.
 This is like outline-forward-same-level, but invisible headings are ok."
   (interactive "p")
-  (outline-back-to-heading t)
+  (org-back-to-heading t)
   (while (> arg 0)
     (let ((point-to-move-to (save-excursion
 			      (org-get-next-sibling))))