greatly simplified the testing README

testing/README.org

@@ -1,115 +1,41 @@
+# -*- mode:org -*-
 #+Title: Org-mode Testing
-#+Babel: results silent
-
-The following instructions describe how to get started using the
-Org-mode test framework.
-
-* To run the tests interactively
-  :PROPERTIES:
-  :tangle:   no
-  :END:
-1) Install the jump.el testing dependency which is included as a git
-   submodule in the org-mode repository.  To do so run the following
-   git submodule commands from inside the base of the Org-mode
-   directory (or just execute the following code block).
-
-   #+begin_src sh
-     cd ..
-     git submodule init
-     git submodule update
-   #+end_src
-
-2) Load the [[file:org-test.el][org-test.el]] file
-   #+begin_src emacs-lisp
-     (load-file "org-test.el")
-   #+end_src
-
-3) The =org-test-jump= command is now bound to =M-C-j= in all
-   emacs-lisp files.  Call this command from any file in the =lisp/=
-   directory of the org-mode repository to jump to the related test
-   file in the =testing/= directory.  Call this functions with a
-   prefix argument, and the corresponding test file will be stubbed
-   out if it doesn't already exist.
-
-4) Ingest the library-of-babel.org file since some tests require this.
-   #+begin_src emacs-lisp
-     (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
-   #+end_src
-
-5) [[info:ert#Top][Review the ERT documentation]] 
-
-6) A number of org-mode-specific functions and macros are provided in
-   =org-test.el= see the [[file:org-test.el::%3B%3B%3B%20Functions%20for%20writing%20tests][;;; Functions for Writing Tests]] subsection of
-   that file.  Some of these functions make use of example org-mode
-   files located in the [[file:examples][examples/]] directory.
-
-7) Functions for loading and running the Org-mode tests are provided
-   in the [[file:org-test.el::%3B%3B%3B%20Load%20and%20Run%20tests][;;; Load and Run Tests]] subsection, the most important of
-   which are
-   - =org-test-load= which loads the entire Org-mode test suite
-   - =org-test-current-defun= which runs all tests for the current
-     function around point (should be called from inside of an
-     Org-mode elisp file)
-   - =org-test-run-all-tests= which runs the entire Org-mode test suite
-   - also note that the =ert= command can also be used to run tests
-
-8) Load and run all tests
-   #+begin_src emacs-lisp 
-     (load-file "org-test.el")
-     (org-babel-lob-ingest "../contrib/babel/library-of-babel.org")
-     (org-test-load)
+#+Property: results silent
+
+* dependencies
+The only dependency is [[http://www.emacswiki.org/emacs/ErtTestLibrary][ERT]] the Emacs testing library which ships with
+Emacs24.  If you are running an older version of Emacs and don't
+already have ERT installed it can be installed from its old [[https://github.com/ohler/ert][git
+repository]].
+
+* non-interactive batch testing from the command line
+The simplest way to run the Org-mode test suite is from the command
+line with the following invocation.  Note that the paths below are
+relative to the base of the Org-mode directory.
+#+BEGIN_SRC sh
+  emacs -Q --batch -l lisp/org.el -l testing/org-test.el \
+      --eval "(progn (org-reload) (setq org-confirm-babel-evaluate nil))" \
+      -f org-test-run-batch-tests
+#+END_SRC
+
+The options in the above command are explained below.
+| -Q      | ignores any personal configuration ensuring a vanilla Emacs instance is used |
+| --batch | runs Emacs in "batch" mode with no gui and termination after execution       |
+| -l      | loads Org-mode and the org mode test suite defined in testing/org-test.el    |
+| --eval  | reloads Org-mode and allows evaluation of code blocks by the tests           |
+| -f      | actually runs the tests using the `org-test-run-batch-tests' function        |
+
+* interactive testing from within Emacs
+To run the Org-mode test suite from a current Emacs instance simply
+load and run the test suite with the following commands.
+
+1) First load the test suite.
+   #+BEGIN_SRC emacs-lisp :var here=(buffer-file-name)
+     (add-to-list 'load-path (file-name-directory here))
+     (require 'org-test)
+   #+END_SRC
+
+2) Then run the test suite.
+   #+BEGIN_SRC emacs-lisp
      (org-test-run-all-tests)
-   #+end_src
-
-* To run the tests in batch mode
-First tangle this file out to your desktop.
-#+headers: :tangle ~/Desktop/run-org-tests.el
-#+begin_src emacs-lisp :var org-dir=(expand-file-name ".." (file-name-directory (or load-file-name (buffer-file-name))))
-  ;; add to the load path
-  (add-to-list 'load-path (concat org-dir "/lisp/"))
-  (add-to-list 'load-path (concat org-dir "/lisp/testing/"))
-  (add-to-list 'load-path (concat org-dir "/lisp/testing/ert/"))
-  
-  ;; load Org-mode
-  (require 'org)
-  
-  ;; setup the ID locations used in tests
-  (require 'org-id)
-  (org-id-update-id-locations
-   (list (concat org-dir "/testing/examples/babel.org")
-         (concat org-dir "/testing/examples/ob-C-test.org")
-         (concat org-dir "/testing/examples/normal.org")
-         (concat org-dir "/testing/examples/ob-awk-test.org")
-         (concat org-dir "/testing/examples/ob-octave.org")
-         (concat org-dir "/testing/examples/ob-fortran-test.org")
-         (concat org-dir "/testing/examples/ob-maxima-test.org")
-         (concat org-dir "/testing/examples/link-in-heading.org")
-         (concat org-dir "/testing/examples/links.org")))
-  
-  ;; ensure that the latest Org-mode is loaded
-  (org-reload)
-  
-  ;; load the test suite
-  (load-file (concat org-dir "/testing/org-test.el"))
-  
-  ;; configure Babel
-  (org-babel-lob-ingest (concat org-dir "/contrib/babel/library-of-babel.org"))
-  (org-babel-do-load-languages
-   'org-babel-load-languages
-   '((emacs-lisp . t)
-     (sh . t)))
-  (setq org-confirm-babel-evaluate nil)
-  
-  ;; run the test suite
-  (org-test-run-all-tests)
-  
-  ;; print the results
-  (with-current-buffer "*ert*"
-    (print (buffer-string)))
-#+end_src
-
-Then run the test suite with the following command which could use any
-version of Emacs.
-#+begin_src sh :results output silent
-  emacs --batch -Q -l ~/Desktop/run-org-tests.el
-#+end_src
+   #+END_SRC