--- a/doc/interpreter/testfun.txi	Wed Dec 14 11:57:55 2011 -0800
+++ b/doc/interpreter/testfun.txi	Wed Dec 14 14:48:47 2011 -0800
@@ -34,20 +34,20 @@
 
 @DOCSTRING(test)
 
-@code{test} scans the named script file looking for lines which
-start with @code{%!}.  The prefix is stripped off and the rest of the
-line is processed through the Octave interpreter.  If the code
+@code{test} scans the named script file looking for lines which start
+with the identifier @samp{%!}.  The prefix is stripped off and the rest
+of the line is processed through the Octave interpreter.  If the code
 generates an error, then the test is said to fail.
 
 Since @code{eval()} will stop at the first error it encounters, you must
 divide your tests up into blocks, with anything in a separate
 block evaluated separately.  Blocks are introduced by the keyword
-@code{test} immediately following the @code{%!}.  For example:
+@code{test} immediately following @samp{%!}.  For example:
 
 @example
 @group
-   %!test error ("this test fails!");
-   %!test "test doesn't fail. it doesn't generate an error";
+%!test error ("this test fails!");
+%!test "test doesn't fail. it doesn't generate an error";
 @end group
 @end example
 
@@ -55,9 +55,9 @@
 
 @example
 @group
-     ***** test error ('this test fails!')
-   !!!!! test failed
-   this test fails!
+  ***** test error ("this test fails!")
+!!!!! test failed
+this test fails!
 @end group
 @end example
 
@@ -66,16 +66,16 @@
 
 @example
 @group
-   %!test
-   %! @var{a} = [1, 2, 3; 4, 5, 6]; B = [1; 2];
-   %! expect = [ @var{a} ; 2*@var{a} ];
-   %! get = kron (@var{b}, @var{a});
-   %! if (any(size(expect) != size(get)))
-   %!    error ("wrong size: expected %d,%d but got %d,%d",
-   %!           size(expect), size(get));
-   %! elseif (any(any(expect!=get)))
-   %!    error ("didn't get what was expected.");
-   %! endif
+%!test
+%! @var{a} = [1, 2, 3; 4, 5, 6]; B = [1; 2];
+%! expect = [ @var{a} ; 2*@var{a} ];
+%! get = kron (@var{b}, @var{a});
+%! if (any (size (expect) != size (get)))
+%!   error ("wrong size: expected %d,%d but got %d,%d",
+%!          size(expect), size(get));
+%! elseif (any (any (expect != get)))
+%!   error ("didn't get what was expected.");
+%! endif
 @end group
 @end example
 
@@ -84,9 +84,9 @@
 
 @example
 @group
-   %!test
-   %! @var{a} = [1, 2, 3; 4, 5, 6]; @var{b} = [1; 2];
-   %! assert (kron (@var{b}, @var{a}), [ @var{a}; 2*@var{a} ]);
+%!test
+%! @var{a} = [1, 2, 3; 4, 5, 6]; @var{b} = [1; 2];
+%! assert (kron (@var{b}, @var{a}), [ @var{a}; 2*@var{a} ]);
 @end group
 @end example
 
@@ -95,8 +95,8 @@
 
 @example
 @group
-   %!test assert (1+eps, 1, 2*eps)          # absolute error
-   %!test assert (100+100*eps, 100, -2*eps) # relative error
+%!test assert (1+eps, 1, 2*eps)          # absolute error
+%!test assert (100+100*eps, 100, -2*eps) # relative error
 @end group
 @end example
 
@@ -105,8 +105,8 @@
 
 @example
 @group
-   %!test assert (isempty([]))
-   %!test assert ([ 1,2; 3,4 ] > 0)
+%!test assert (isempty ([]))
+%!test assert ([1, 2; 3, 4] > 0)
 @end group
 @end example
 
@@ -114,16 +114,32 @@
 is a shorthand form:
 
 @example
-   %!assert (@dots{})
+%!assert (@dots{})
 @end example
 
 @noindent
 which is equivalent to:
 
 @example
-   %!test assert (@dots{})
+%!test assert (@dots{})
 @end example
 
+Occasionally a block of tests will depend on having optional
+functionality in Octave.  Before testing such blocks the availability of
+the required functionality must be checked.  A @code{%!testif HAVE_XXX}
+block will only be run if Octave was compiled with functionality
+@samp{HAVE_XXX}.  For example, the sparse single value decomposition,
+@code{svds()}, depends on having the @sc{arpack} library.  All of the tests
+for @code{svds} begin with
+
+@example
+%!testif HAVE_ARPACK
+@end example
+
+@noindent
+Review @file{config.h} or @code{octave_config_info ("DEFS")} to see some
+of the possible values to check.
+
 Sometimes during development there is a test that should work but is
 known to fail.  You still want to leave the test in because when the
 final code is ready the test should pass, but you may not be able to
@@ -132,45 +148,49 @@
 
 @example
 @group
-   %!xtest assert (1==0)
-   %!xtest fail ('success=1','error'))
+%!xtest assert (1==0)
+%!xtest fail ("success=1", "error")
 @end group
 @end example
 
-Another use of @code{xtest} is for statistical tests which should
-pass most of the time but are known to fail occasionally.
+@noindent
+In this case, the test will run and any failure will be reported.
+However, testing is not aborted and subsequent test blocks will be
+processed normally.  Another use of @code{xtest} is for statistical
+tests which should pass most of the time but are known to fail
+occasionally.
 
 Each block is evaluated in its own function environment, which means
 that variables defined in one block are not automatically shared
 with other blocks.  If you do want to share variables, then you
 must declare them as @code{shared} before you use them.  For example, the
 following declares the variable @var{a}, gives it an initial value (default
-is empty), then uses it in several subsequent tests.
+is empty), and then uses it in several subsequent tests.
 
 @example
 @group
-   %!shared @var{a}
-   %! @var{a} = [1, 2, 3; 4, 5, 6];
-   %!assert (kron ([1; 2], @var{a}), [ @var{a}; 2*@var{a} ]);
-   %!assert (kron ([1, 2], @var{a}), [ @var{a}, 2*@var{a} ]);
-   %!assert (kron ([1,2; 3,4], @var{a}), [ @var{a},2*@var{a}; 3*@var{a},4*@var{a} ]);
+%!shared @var{a}
+%! @var{a} = [1, 2, 3; 4, 5, 6];
+%!assert (kron ([1; 2], @var{a}), [ @var{a}; 2*@var{a} ]);
+%!assert (kron ([1, 2], @var{a}), [ @var{a}, 2*@var{a} ]);
+%!assert (kron ([1,2; 3,4], @var{a}), [ @var{a},2*@var{a}; 3*@var{a},4*@var{a} ]);
 @end group
 @end example
 
 You can share several variables at the same time:
 
 @example
-   %!shared @var{a}, @var{b}
+%!shared @var{a}, @var{b}
 @end example
 
 You can also share test functions:
 
 @example
 @group
-   %!function @var{a} = fn (@var{b})
-   %!  @var{a} = 2*@var{b};
-   %!endfunction
-   %!assert (@var{fn}(2), 4);
+%!function @var{a} = fn (@var{b})
+%!  @var{a} = 2*@var{b};
+%!endfunction
+%!assert (fn(2), 4);
 @end group
 @end example
 
@@ -183,13 +203,13 @@
 For example:
 
 @example
-   %!error <passes!> error('this test passes!');
+%!error <passes!> error ("this test passes!");
 @end example
 
 If the code doesn't generate an error, the test fails.  For example:
 
 @example
-   %!error "this is an error because it succeeds.";
+%!error "this is an error because it succeeds.";
 @end example
 
 @noindent
@@ -197,23 +217,23 @@
 
 @example
 @group
-   ***** error "this is an error because it succeeds.";
-   !!!!! test failed: no error
+  ***** error "this is an error because it succeeds.";
+!!!!! test failed: no error
 @end group
 @end example
 
 It is important to automate the tests as much as possible, however
 some tests require user interaction.  These can be isolated into
 demo blocks, which if you are in batch mode, are only run when 
-called with @code{demo} or @code{verbose}.  The code is displayed before
-it is executed.  For example,
+called with @code{demo} or the @code{verbose} option to @code{test}.
+The code is displayed before it is executed.  For example,
 
 @example
 @group
-   %!demo
-   %! @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t});
-   %! plot(@var{t},@var{x});
-   %! you should now see a sine wave in your figure window
+%!demo
+%! @var{t} = [0:0.01:2*pi]; @var{x} = sin (@var{t});
+%! plot (@var{t}, @var{x});
+%! # you should now see a sine wave in your figure window
 @end group
 @end example
 
@@ -222,10 +242,12 @@
 
 @example
 @group
-   > @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t});
-   > plot(@var{t},@var{x});
-   > you should now see a sine wave in your figure window
-   Press <enter> to continue: 
+funcname example 1:
+ @var{t} = [0:0.01:2*pi]; @var{x} = sin (@var{t});
+ plot (@var{t}, @var{x});
+ # you should now see a sine wave in your figure window
+
+Press <enter> to continue: 
 @end group
 @end example
 
@@ -234,23 +256,29 @@
 
 If you want to temporarily disable a test block, put @code{#} in place
 of the block type.  This creates a comment block which is echoed
-in the log file, but is not executed.  For example:
+in the log file but not executed.  For example:
 
 @example
 @group
-   %!#demo
-   %! @var{t}=[0:0.01:2*pi]; @var{x}=sin(@var{t});
-   %! plot(@var{t},@var{x});
-   %! you should now see a sine wave in your figure window
+%!#demo
+%! @var{t} = [0:0.01:2*pi]; @var{x} = sin (@var{t});
+%! plot (@var{t}, @var{x});
+%! # you should now see a sine wave in your figure window
 @end group
 @end example
 
-Block type summary:
+@subsubheading Block type summary:
 
 @table @code
 @item %!test
 check that entire block is correct
 
+@item %!testif HAVE_XXX
+check block only if Octave was compiled with feature HAVE_XXX.
+
+@item %!xtest
+check block, report a test failure but do not abort testing.
+
 @item %!error
 check for correct error message
 
@@ -277,15 +305,16 @@
 @end table
 
 You can also create test scripts for builtins and your own C++
-functions.  Just put a file of the function name on your path without
-any extension and it will be picked up by the test procedure.  You
-can even embed tests directly in your C++ code:
+functions.  To do so put a file with the bare function name (no .m
+extension) in a directory in the load path and it will be discovered by
+the @code{test} function.  Alternatively, you can embed tests directly in your
+C++ code:
 
 @example
 @group
-   #if 0
-   %!test disp('this is a test')
-   #endif
+#if 0
+%!test disp ("this is a test")
+#endif
 @end group
 @end example
 
@@ -294,21 +323,16 @@
 
 @example
 @group
-   /*
-   %!test disp('this is a test')
-   */
+/*
+%!test disp ("this is a test")
+*/
 @end group
 @end example
 
 @noindent
-but then the code will have to be on the load path and the user 
-will have to remember to type test('name.cc').  Conversely, you
-can separate the tests from normal Octave script files by putting
-them in plain files with no extension rather than in script files.
-@c DO I WANT TO INCLUDE THE EDITOR SPECIFIC STATEMENT BELOW???
-@c Don't forget to tell emacs that the plain text file you are using
-@c is actually octave code, using something like:
-@c   -*-octave-*-
+However, in this case the raw source code will need to be on the load
+path and the user will have to remember to type
+@code{test ("funcname.cc")}.
 
 @DOCSTRING(assert)
 
@@ -319,10 +343,10 @@
 
 @DOCSTRING(demo)
 
+@DOCSTRING(example)
+
 @DOCSTRING(rundemos)
 
 @DOCSTRING(runtests)
 
-@DOCSTRING(example)
-
 @DOCSTRING(speed)