Mercurial > forge
changeset 1275:9108c6729d60 octave-forge
[for Stefan van der Walt] updated documentation and build
| author | pkienzle |
|---|---|
| date | Mon, 09 Feb 2004 16:16:19 +0000 |
| parents | e2daebed2db7 |
| children | 8356bf67497c |
| files | doc/coda/Makefile doc/coda/appendices/examples.sgml doc/coda/coda.sgml doc/coda/oct/advanced.sgml doc/coda/oct/matpow.png doc/coda/oct/oct.sgml doc/coda/oct/quickref.sgml doc/coda/oct/tut-basic.sgml doc/coda/oct/tut-interm.sgml doc/coda/oct/tut-intro.sgml doc/coda/oct/tutorial.sgml doc/coda/standalone/standalone.sgml |
| diffstat | 12 files changed, 489 insertions(+), 503 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/coda/Makefile Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/Makefile Mon Feb 09 16:16:19 2004 +0000 @@ -8,21 +8,29 @@ coidx:=perl /usr/bin/collateindex.pl tidyflags:=--wrap 79 --tidy-mark false -srcdirs:=appendices oct standalone -src:=$(wildcard *.sgml) $(foreach dir,$(srcdirs),$(wildcard $(dir)/*.sgml)) +src_appendices=examples gnufdl gnugpl +src_oct=advanced oct quickref tut-basic tut-interm tut-intro tutorial +src_standalone=standalone +src_base=coda bibliography +src=$(src_appendices:%=appendices/%.sgml) $(src_oct:%=oct/%.sgml) \ + $(src_standalone:%=standalone/%.sgml) $(src_base:%=%.sgml) +.phony: all +all: html pdf targz + .phony: check -check: +check: $(src) grep --line-number $$'\t' $(src) | cat --show-tabs - xml-check coda.sgml + checkXML coda.sgml .phony: clean clean: - rm -f index.sgml - cd $(outputdir) && rm -f *.html *.ps HTML.index - cd $(outputdir) && rm -f coda.{tex,dvi,log,aux,ps.gz,pdf} - cd $(outputdir) && rm -f *.tar.gz + $(RM) index.sgml + cd $(outputdir) && $(RM) *.html *.ps HTML.index matpow.png + cd $(outputdir) && $(RM) coda.{out,tex,dvi,log,aux,ps.gz,pdf} + cd $(outputdir) && $(RM) *.tar.gz + rmdir $(outputdir) coda coda.junk .phony: distclean distclean: clean @@ -32,11 +40,8 @@ www-install: all cd $(outputdir) && install -m 644 -p *.html coda.ps.gz coda.pdf coda-sgml.tar.gz /site/wwwroot/octave/coda -.phony: all -all: html pdf targz - .phony: html -html: $(outputdir)/coda.html +html: $(outputdir)/index.html $(outputdir)/matpow.png .phony: ps ps: $(outputdir)/coda.ps.gz @@ -47,16 +52,15 @@ .phony: targz targz: $(outputdir)/coda-sgml.tar.gz $(outputdir)/coda.ps.gz -$(outputdir)/coda-sgml.tar.gz: $(src) Makefile +$(outputdir)/coda-sgml.tar.gz: $(src) tar czf $@ $^ -$(outputdir)/coda.html: $(src) - @echo '=== Pass 1 ===' - touch index.sgml; true +index.sgml: $(src) -db2html $(dbflags) -V html-index coda.sgml test \! -f $(autoidx) && touch $(autoidx); true $(coidx) $(coidxflags) $(autoidx) > index.sgml - @echo '=== Pass 2 ===' + +$(outputdir)/index.html: $(src) index.sgml -db2html $(dbflags) coda.sgml cd $(outputdir) && tidy -modify $(tidyflags) *.html 2>/dev/null; true cd $(outputdir) && \ @@ -67,7 +71,7 @@ rm $$f.bak; \ done -$(outputdir)/coda.ps: $(src) +$(outputdir)/coda.ps: $(src) index.sgml db2tex coda.sgml cd $(outputdir) && \ cp ../coda.tex . ; jadetex coda.tex ; jadetex coda.tex ; \ @@ -75,9 +79,12 @@ $(outputdir)/coda.ps.gz: $(outputdir)/coda.ps -$(outputdir)/coda.pdf: coda.sgml +$(outputdir)/coda.pdf: $(src) index.sgml db2pdf -o $(outputdir) coda.sgml +$(outputdir)/matpow.png: oct/matpow.png + cp $< $@ + # cd $(outputdir) && \ # gs -q -r600 -dNOPAUSE -dBATCH -sDEVICE=pdfwrite \ # -sOutputFile=coda.pdf coda.ps
--- a/doc/coda/appendices/examples.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/appendices/examples.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,5 +1,6 @@ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -28,7 +29,7 @@ <para> This appendix gathers all examples that are either too long for the main - test, or are referenced but not defined in the main text. + text or are referenced (but not defined in) the main text. </para> <sect1 id = "sect-ex-unittest"> @@ -39,134 +40,219 @@ <secondary>unit test</secondary> </indexterm> -<sect2 id = "sect-ex-unittest-unittest-m"> -<title><filename>unittest.m</filename></title> +<sect2 id = "sect-ex-unittest-unit_init-m"> +<title><filename>unit_init.m</filename></title> <programlisting role = "octave"> -function result = unittest(test_title, expect_pass, actual_result, - verbose) - ## Function unittest compares the result ACTUAL_RESULT from running - ## a test (either 0 for failure, or 1 for success) with the - ## expected outcome of the test EXPECT_PASS (either 0 for expecting - ## a failure, or 1 for expecting pass). TEST_TITLE is the name of - ## the test. All test results will be accompanied by the test's - ## title. +function unit_init(verbosity, global_vars) + ## Initialize the global structure unittest_results, which is needed + ## in all functions of the *unittest module. Debugging information + ## is printed if verbosity==1. global_vars is a cell array of the + ## names of the global variables used in the tests. ## - ## The result of unittest is on of the following: UNRESOLVED: The - ## test did neither return 0 nor 1. PASS: expected pass, got pass. - ## FAIL: expected pass, got fail. UPASS: expected fail, got pass. - ## XFAIL: expected fail, got fail. - ## - ## A call to unittest typically looks like this: - ## - ## unittest("scalar integer addition", 1, eval("1 + 1 == 2;")); - + ## e.g. unit_init(1, {"g", "a", "x"}) + global unittest_results; - - ## Sanity check input parameters - if (nargin < 3 | nargin > 4) - error("Function run_rest expects 3 or 4 parameters."); - endif - - if (!isstr(test_title)) - error("Expecting TEST_TITLE (arg 1) to be a string."); - endif - - if (expect_pass != 0 & expect_pass != 1) - error("Expecting EXPECT_PASS (arg 2) to be 0 or 1."); - endif - - ## Default: verbose = false - if (nargin = 3) - verbose = 0; - endif - - unittest_results.total++; - - ## Take actions depending on what test result we expect - ## (expect_pass), and what we actually got (actual_result). - if (actual_result != 0 & actual_result != 1) - result = "UNRESOLVED"; - unittest_results.unresolved++; - return; + + unittest_results.verbose = 0; + unittest_results.eval_globals = {}; + if (nargin > 0) + if (!isscalar(verbosity) || verbosity < 0 || verbosity > 1) + warning("unit_init: verbose must be 0 or 1"); + else + unittest_results.verbose = verbosity; + endif + + if (nargin == 2 && iscell(global_vars)) + for i = 1:length(global_vars) + unittest_results.eval_globals{i} = strcat("global ", global_vars{i}, ";"); + endfor + else + error("global_vars must be a cell array"); + endif + + if (nargin > 2) + usage("expecting 2 arguments only"); + end endif - - if (expect_pass == 1 & actual_result == 1) - result = "PASS"; - if (verbose != 0) - printf("PASS: %s\n", test_title); - endif - unittest_results.pass++; - elseif (expect_pass == 1 & actual_result == 0) - result = "FAIL"; - printf("FAIL: %s\n", test_title); - unittest_results.fail++; - elseif (expect_pass == 0 & actual_result == 0) - result = "XFAIL"; - printf("XFAIL: %s\n", test_title); - unittest_results.xfail++; - elseif (expect_pass == 0 & actual_result == 1) - result = "UPASS"; - printf("UPASS: %s\n", test_title); - unittest_results.upass++; - endif -endfunction -</programlisting> -</sect2> - -<sect2 id = "sect-ex-unittest-getunittest-m"> -<title><filename>getunittest.m</filename></title> - -<programlisting role = "scilab"> -function r = getunittest() - ## Return the results of previous unittest commands. - - global unittest_results; - - r = unittest_results; -endfunction -</programlisting> -</sect2> - -<sect2 id = "sect-ex-unittest-initunittest-m"> -<title><filename>initunittest.m</filename></title> - -<programlisting role = "scilab"> -function initunittest() - ## Initialize the global structure unittest_results, which is needed - ## in all functions of the *unittest module. - - global unittest_results; - + unittest_results.total = 0; # number of testcases attempted unittest_results.pass = 0; # number of expected passed unittest_results.fail = 0; # number of unexpected failures unittest_results.upass = 0; # number of unexpected passes unittest_results.xfail = 0; # number of expected failures unittest_results.unresolved = 0; # number of unresolved testcases - + default_eval_print_flag = 0; endfunction </programlisting> </sect2> -<sect2 id = "sect-ex-unittest-prunittest-m"> -<title><filename>prunittest.m</filename></title> +<sect2 id = "sect-ex-unittest-unit_test-m"> +<title><filename>unit_test.m</filename></title> -<programlisting role = "scilab"> -function prunittest() - ## Print the results from previous unittest calls in pretty format. +<programlisting role = "octave"> +function result = unit_test(test_title, expect_pass, actual_result) + ## Function unittest compares the ACTUAL_RESULT of running + ## a test (either 0 for failure, or 1 for success) with the + ## expected outcome of the test EXPECT_PASS (either 0 for expecting + ## a failure, or 1 for expecting pass). TEST_TITLE is the name of + ## the test. All test results will be accompanied by the test's + ## title. + ## + ## The result of unittest is on of the following: UNRESOLVED: The + ## test did neither return 0 nor 1. PASS: expected pass, got pass. + ## FAIL: expected pass, got fail. UPASS: expected fail, got pass. + ## XFAIL: expected fail, got fail. + ## + ## A call to unittest typically looks like this: + ## + ## unittest("scalar integer addition", 1, eval("1 + 1 == 2;")); + + global unittest_results; + + ## Sanity check input parameters + if ( nargin < 3 | nargin > 4 ) + error("Function run_rest expects 3 or 4 parameters."); + endif + + if (!isstr(test_title)) + error("Expecting TEST_TITLE (arg 1) to be a string."); + endif + + if (expect_pass != 0 & expect_pass != 1) + error("Expecting EXPECT_PASS (arg 2) to be 0 or 1."); + endif + + unittest_results.total++; - global unittest_results; + ## Take actions depending on what test result we expect + ## (expect_pass), and what we actually got (actual_result). + if (actual_result != 0 & actual_result != 1) + result = "UNRESOLVED"; + unittest_results.unresolved++; + if (actual_result == 2) + printf("SYNTAX ERROR: %s\n", test_title); + endif + return; + endif + + if (expect_pass == 1 & actual_result == 1) + result = "PASS"; + if (unittest_results.verbose != 0) + printf("PASS: %s\n", test_title); + else + printf('.'); + endif + unittest_results.pass++; + elseif (expect_pass == 1 & actual_result == 0) + result = "FAIL"; + printf("FAIL: %s\n\n", test_title); + unittest_results.fail++; + elseif (expect_pass == 0 & actual_result == 0) + result = "XFAIL"; + printf("XFAIL: %s\n", test_title); + unittest_results.xfail++; + elseif (expect_pass == 0 & actual_result == 1) + result = "UPASS"; + printf("UPASS: %s\n", test_title); + unittest_results.upass++; + endif + endfunction +</programlisting> +</sect2> - printf("# of testcases attempted %d\n", unittest_results.total); - printf("# of expected passes %d\n", unittest_results.pass); - printf("# of expected failures %d\n", unittest_results.xfail); - printf("# of unexpected passes %d\n", unittest_results.upass); - printf("# of unexpected failures %d\n", unittest_results.fail); - printf("# of unresolved testcases %d\n", unittest_results.unresolved); +<sect2 id = "sect-ex-unittest-unit_test_equals-m"> +<title><filename>unit_test_equals.m</filename></title> + +<programlisting role = "octave"> +function unit_test_equals(test_title, result_A, result_B) + + unit_test(test_title, 1, all(all(result_A == result_B))); + endfunction </programlisting> </sect2> + +<sect2 id = "sect-ex-unittest-unit_test_err-m"> +<title><filename>unit_test_err.m</filename></title> + +<programlisting role = "octave"> +function unit_test_err(test_title, expected_error_prefix, evaluated_string) + + unit_test(test_title, 1, erreval(expected_error_prefix, evaluated_string)); + +endfunction +</programlisting> +</sect2> + +<sect2 id = "sect-ex-unittest-errcheck-m"> +<title><filename>errcheck.m</filename></title> + +<programlisting role = "octave"> +function e = errcheck(error_prefix) + + e = 1; + if (index(__error_text__, error_prefix) != 1) + e = 0; + printf("\nUNEXPECTED ERROR: %s", __error_text__); + endif + +end +</programlisting> +</sect2> + +<sect2 id = "sect-ex-unittest-erreval-m"> +<title><filename>erreval.m</filename></title> + +<programlisting role = "octave"> +function rv = erreval(error_prefix, try_str, catch_str) + ## erreval() extends the built-in function eval(). Return 0 if + ## try_str does not raise the error of type error_prefix, return 1 + ## otherwise. + + global unittest_results; + for k = 1:length(unittest_results.eval_globals) + eval(unittest_results.eval_globals{k}); + end + + rv = 0; + try + eval(try_str); + catch + rv = errcheck(error_prefix); + end + +endfunction +</programlisting> +</sect2> + +<sect2 id = "sect-ex-unittest-unit_results-m"> +<title><filename>unit_results.m</filename></title> + +<programlisting role = "octave"> + function unit_results() + ## Print the results from previous unittest calls in pretty format. + + global unittest_results; + + printf("\n"); + printf("# of testcases attempted %d\n", unittest_results.total); + printf("# of expected passes %d\n", unittest_results.pass); + printf("# of expected failures %d\n", unittest_results.xfail); + printf("# of unexpected passes %d\n", unittest_results.upass); + printf("# of unexpected failures %d\n", unittest_results.fail); + printf("# of unresolved testcases %d\n", unittest_results.unresolved); + printf("\n"); + + if (unittest_results.total == unittest_results.pass + unittest_results.xfail) + printf("Unit testing completed successfully!\n"); + else + printf("One or more tests failed!\n"); + endif + endfunction +</programlisting> +</sect2> + </sect1> </appendix>
--- a/doc/coda/coda.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/coda.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,9 +1,10 @@ <?xml version="1.0" standalone="no"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" - "/usr/share/sgml/docbook/xml-dtd-4.1/docbookx.dtd" [ + "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -71,6 +72,13 @@ <authorinitials>cls</authorinitials> <revremark>Initial revision</revremark> </revision> + + <revision> + <revnumber>0.2</revnumber> + <date>2004-02-06</date> + <authorinitials>sjw</authorinitials> + <revremark>Corrections, unit testing improved</revremark> + </revision> </revhistory> <authorgroup> @@ -82,6 +90,7 @@ <orgname>Hammersmith Consulting</orgname> </affiliation> </author> + </authorgroup> <copyright> @@ -89,6 +98,11 @@ <holder>Ch. L. Spiel</holder> </copyright> + <copyright> + <year>2004</year> + <holder>Stefan van der Walt</holder> + </copyright> + <legalnotice> <para> Permission is granted to copy, distribute and/or modify this
--- a/doc/coda/oct/advanced.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/oct/advanced.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -64,14 +64,14 @@ <para> The definition of constants and variables in a dynamically linked - GNU/Octave extension resembles the header of a dynamically linked function. - (See, for example, <xref linkend = "sect-oct-tutorial-oct1"></xref>) + GNU/Octave extension resembles the header of a dynamically linked function + (see, for example, <xref linkend = "sect-oct-tutorial-oct1"></xref>). However, the appropriate macro <function role = "macro">DEFCONST</function> is not available when creating a dynamically loadable extension for it is defined in <filename class = "headerfile">defun.h</filename> and not in <filename class = "headerfile">defun-dld.h</filename>. The latter is necessary to set up an dynamically loadable extension. The easiest, - moderately clean way os to duplicate <function role = + moderately clean way is to duplicate <function role = "macro">DEFCONST</function>'s definition from <filename class = "headerfile">defun.h</filename> into the respective extension. </para> @@ -97,9 +97,9 @@ <para> <function role = "macro">DEFCONST</function> introduces a constant named - <token>constant_name</token> at the interpreter level, giving it the value - of <token>defining_expression</token> and endowing it with the - documentation <replaceable>documentation_string</replaceable>. The newly + <constant>constant_name</constant> at the interpreter level, giving it the value + of <varname>defining_expression</varname> and endowing it with the + documentation <varname>documentation_string</varname>. The newly created constant will be protected against deletion, but <emphasis>not</emphasis> against change. </para> @@ -110,14 +110,14 @@ <type>void</type> <function role = "macro">DEFCONST</function>(<token>constant_name</token>, <token>defining_expression</token>, - <type>const std::string&</type> <replaceable>documentation_string</replaceable>) + <type>const std::string&</type> <varname>documentation_string</varname>) </literallayout> <para> - The name of the constant <token>constant_name</token> must be a valid + The name of the constant <constant>constant_name</constant> must be a valid C++ identifier, because it is <emphasis>not</emphasis> quoted. Octave automatically casts the variable's definition, - <replaceable>defining_expression</replaceable>, to + <varname>defining_expression</varname>, to type <type>octave_value</type>. </para> @@ -160,7 +160,7 @@ DEFCONST(c, 2.99792458e8, "Speed of light in m/s."); DEFCONST(hbar, h / (2.0 * M_PI), - "Reduced Planck's constant hbar, this is, h/(2*pi) in J*s."); + "Reduced Planck's constant hbar, that is, h/(2*pi) in J*s."); DEFCONST(G, 6.672e-11, "Graviation constant in N*m^2/kg^2."); DEFCONST(e, 1.6021892e-19, @@ -191,6 +191,11 @@ DEFCONST(hbar, h / (2.0 * M_PI), DOCSTRING_HBAR); </programlisting> + + <para> + This is also useful for describing the function's + documentation string. + </para> </tip> <indexterm> @@ -236,15 +241,15 @@ <literallayout class = "monospaced"> <type>void</type> -<function role = "macro">DEFVAR</function>(<token>variable_name</token>, - <token>defining_expression</token>, +<function role = "macro">DEFVAR</function>(<varname>variable_name</varname>, + <varname>defining_expression</varname>, <type>symbol_record::change_function</type> <replaceable>changing_function</replaceable>, <type>const std::string&</type> <replaceable>documentation_string</replaceable>) </literallayout> <para> - The parameters <token>variable_name</token>, - <token>defining_expression</token>, and + The parameters <varname>variable_name</varname>, + <replaceable>defining_expression</replaceable>, and <replaceable>documentation_string</replaceable> are analogous to those of <function role = "macro">DEFCONST</function>. Only <replaceable>changing_function</replaceable> calls for further explanation. @@ -394,7 +399,7 @@ #define DOCSTRING_COUNTER \ "Variable `counter' is initialized to 1.0.\n\ It is linked to the C++ variable `counter_var' in file `defvar.cc'.\n\ -Whenever `counter_var' is assigned to the number of assigments\n\ +Whenever `counter' is assigned to the number of assigments\n\ is printed." //
--- a/doc/coda/oct/oct.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/oct/oct.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,5 +1,6 @@ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -54,22 +55,22 @@ Why would you ever want to write in C++ again, having the wonderful &octave-app; environment at your service? Well, sometimes the performance of native Octave-code is not enough to attack a problem. Octave-code is - interpreted, thus it is inherently slow executed (especially if the problem - cannot be vectorized). In such a case moving from + interpreted, thus it is inherently slow when executed (especially if the + problem cannot be vectorised). In such a case moving from <filename>m</filename>-code to compiled C++-code speeds up the execution by a factor of ten or more. The second group of problems, where reverting to - low-level code is necessary, is interfacing with foreign libraries (think - of LAPACK) or routines written in a language other than C++, most notably - Fortran-77. + low-level code is necessary, is when interfacing with foreign libraries + (think of LAPACK) or routines written in languages other than C++, most + notably Fortran-77. </para> <para> - Having convinced ourselves that we have to bite the bullet, we start with a - easy tutorial (<xref linkend = "sect-oct-tutorial"></xref>), which will - teach any reader who is sufficiently used to C++, how to write her first + Having convinced ourselves that we have to bite the bullet, we start with + an easy tutorial (<xref linkend = "sect-oct-tutorial"></xref>). This will + teach any reader who is sufficiently used to C++ how to write her first dynamically linked extension for &octave-app;. Having guided the reader with her first steps, <xref linkend = "sect-oct-advanced"></xref> covers - more advanded topics of writing extensions. For later reference, we + more advanced topics of writing extensions. For later reference, we provide a quick reference of the most helpful methods of the Octave interface classes in <xref linkend = "sect-oct-quick-ref"></xref>. </para>
--- a/doc/coda/oct/quickref.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/oct/quickref.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,5 +1,6 @@ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -44,11 +45,27 @@ modifiers in the class' synopis. </para> +<para> + To generate an up-to-date class reference using doxygen, issue the + command + <programlisting> doxygen -g octave-dox </programlisting> + + Edit <filename>octave-dox</filename>, set + <varname>EXTRACT_ALL</varname> and + <varname>RECURSIVE</varname> to YES and + <varname>INPUT</varname> to the location of the Octave include + files, e.g. <filename>/usr/include/octave-2.1.50</filename>. + + Now execute + <programlisting>doxygen octave-dox</programlisting> + to generate the documentation in <filename>./html</filename>. +</para> + <sect2 id = "sect-qr-types"> <title>Types</title> <para> - We follow the old tradition from the days of Pascal, and introduce first + We follow the old tradition from the days of Pascal and introduce first the types the &octave-app; library works on. </para> @@ -295,6 +312,20 @@ Complex (<type>double</type>) valued diagonal matrix. </entry> </row> + + <row> + <entry><type>Cell array</type></entry> + + <entry> + <filename class ="headerfile">ov-cell.h</filename>, + <filename class = "headerfile">Cell.h</filename>, + </entry> + + <entry> + Cell array. + </entry> + </row> + </tbody> </tgroup> </table>
--- a/doc/coda/oct/tut-basic.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/oct/tut-basic.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,5 +1,6 @@ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -29,7 +30,7 @@ </para> <sect3 id = "sect-oct-tutorial-feature-compatability"> -<title>Feature Compatability</title> +<title>Feature Compatibility</title> <para> In principle, the functions defined in <filename>oct</filename>-files must @@ -135,18 +136,19 @@ <para> Before we start to write a low-level implementation of - <function>matpow</function>, we look at the most essential types and - methods to handle data that flows through the Octave-interpreter interface. + <function>matpow</function>, we look at the most essential types + and methods used to handle data that flows through the + Octave-interpreter interface. </para> <para> - As has been said above, the arguments passed to a dynamically loaded - functions are bundeled in an <type>octave_value_list</type>. Results + As has been said above, the arguments passed to dynamically loaded + functions are bundled in an <type>octave_value_list</type>. Results returned from a function are also passed in an <type>octave_value_list</type>. The default constructor, - <methodname>octave_value_list</methodname>, creates an empty list, which + <methodname>octave_value_list</methodname>, creates an empty list which, when used as return value, yields an Octave function returning - <quote>void</quote>. To access the elements of a list, following methods + <quote>void</quote>. To access the elements of a list the following methods form class <classname>octave_value_list</classname> (defined in OCT/src/<filename class = "headerfile">oct-obj.h</filename>) are useful: </para> @@ -204,22 +206,23 @@ </classsynopsis> <para> - <methodname>length</methodname> returns the number of elements in the list. - The overloaded parenthesis select a single element from the list. The - index base for <replaceable>index</replaceable> is 0, and - <emphasis>not</emphasis> 1 as Fortran adepts might infer. The LHS or RHS - values returned by <methodname>operator()</methodname> are - <type>octave_value</type>s, i.e., they can carry any type known to Octave, + <methodname>length</methodname> returns the number of elements in + the list. The overloaded parenthesis operator selects a single + element from the list. The index base for + <replaceable>index</replaceable> is 0 and <emphasis>not</emphasis> + 1 as Fortran adepts might infer. The value returned by + <methodname>operator()</methodname> is an + <type>octave_value</type>, i.e., any type known to Octave, e.g. integers, real matrices, complex matrices, and so on. </para> <para> - Knowing how to access the arguments of unspecified type, the next thing we - would like to do is get their values. &octave-app; follows a uniform - naming scheme: all functions that return an object of a cerain type end in - <literal>_type</literal>. Some of the more important of these methods - (defined in OCT/src/<filename class = "headerfile">ov-base.h</filename>) - are: + Knowing how to access the arguments of unspecified type, the next + thing we would like to do is get their values. &octave-app; + follows a uniform naming scheme: all functions that return an + object of a certain type ends in <literal>_type</literal>. Some + of the more important of these methods (defined in + OCT/src/<filename class = "headerfile">ov-base.h</filename>) are: </para> <classsynopsis language = "cpp"> @@ -291,7 +294,7 @@ <title>C++ implementation of <function>matpow</function></title> <programlisting role = "c++"> -#include <oct.h> +#include <octave/oct.h> static bool is_even(int n); @@ -303,12 +306,14 @@ const int n = args(1).int_value(); <co id = "co-int-value"></co> if (n == 0) - return DiagMatrix(args(0).rows()<co id = "co-matrix-rows"></co>, args(0).columns()<co id = "co-matrix-columns"></co>, 1.0); <co id = "co-diagmatrix-constructor"></co> + return octave_value( + DiagMatrix(args(0).rows()<co id = "co-matrix-rows"></co>, args(0).columns()<co id = "co-matrix-columns"></co>, 1.0) <co id = "co-diagmatrix-constructor"></co> + ); if (n == 1) - return args(0); <co id = "co-return-input-arg"></co> + return args(0); Matrix p(args(0).matrix_value()); <co id = "co-matrix-copy-constructor"></co> - Matrix b(args(0).matrix_value()); + Matrix b(p); int np = n - 1; while (np >= 1) { @@ -324,7 +329,7 @@ p = p * p; } - return b; <co id = "co-ovl-from-matrix-constructor"></co> + return octave_value(b); <co id = "co-ovl-from-matrix-constructor"></co> } @@ -341,14 +346,14 @@ Get the exponent <varname>n</varname>, which is the <emphasis>second</emphasis> argument to <function>matpow</function> through - <methodname>args</methodname>(1), and retrieve its integral + <methodname>args</methodname>(1) and retrieve its integral value with <methodname>int_value</methodname>. </para> </callout> <callout arearefs = "co-matrix-rows"> <para> - The matrix that we want to raise to the n-th power, is the + The matrix that we want to raise to the n-th power is the <emphasis>first</emphasis> argument, therefore it is accessed through <methodname>args</methodname>(0). The method <methodname>rows</methodname> returns the number of rows in the @@ -378,32 +383,11 @@ </para> </callout> - <callout arearefs = "co-return-input-arg"> - <para> - If n = 1 the answer is the same matrix as the input - matrix. For we want to save time and space, and not return a - copy of the input matrix by using - </para> - - <programlisting role = "c++"> -return args(0).matrix_value(); - </programlisting> - - <para> - Though the latter would work, because constructor <methodname - role = "constructor">octave_value_list</methodname>(<type>const - Matrix&</type> <replaceable>m</replaceable>) converts the - matrix into a list, we avoid the copy operation and simply - return the <type>octave_value</type> - <literal>args(0)</literal>. - </para> - </callout> - <callout arearefs = "co-matrix-copy-constructor"> <para> - Initialize the matrix <varname>p</varname>, that will take the + Initialise the matrix <varname>p</varname> that will store the powers of the base. The <classname>Matrix</classname> - constructor cannot take an <type>octave_value</type>, and we + constructor cannot take an <type>octave_value</type> and we have to supply the matrix itself by invoking <methodname>matrix_value</methodname>. </para> @@ -417,12 +401,13 @@ <tip> <para> - The Octave library overloads all elementary operations of - scalars, (row-/column-) vectors, and matrices. If in - doubt, whether a particular operation has been overloaded - it is faster to try by compiling than to look at (read: - grep through) all the sources, because in most cases the - desired elementary operation is implemented. + The Octave library overloads all elementary + operations of scalars, (row-/column-) vectors and + matrices. If in doubt as to whether a particular + operation has been overloaded, simply try it. It + takes less time than browsing (read: grep through) + all the sources – the desired elementary + operation is implemented in most cases. </para> </tip> </callout> @@ -430,15 +415,15 @@ <callout arearefs = "co-ovl-from-matrix-constructor"> <para> We can return the result matrix <varname>b</varname> - directly, as an apropriate constructor is invoked to convert it - to an <type>octave-value_list</type>. + directly, as an appropriate constructor is invoked to convert it + to an <type>octave_value_list</type>. </para> </callout> </calloutlist> </example> <para> - We learn from the example that the C++ resembles closely the Octave + We learn from the example that the C++ closely resembles the Octave function. This is due to the clever class structure of the Octave library. </para> @@ -459,15 +444,16 @@ </para> <screen> -<prompt>cspiel@hydra$</prompt> <userinput>ls</userinput> -Makefile matpow.cc matrix-power.m testmp.m -<prompt>cspiel@hydra$</prompt> <userinput>mkoctfile matpow.cc</userinput> +<prompt>$</prompt> <userinput>ls</userinput> +Makefile matpow0.m matpow1.m matpow.cc test_matpow.m +<prompt>$</prompt> <userinput>mkoctfile matpow.cc</userinput> </screen> <para> - Nice, but not enough! Presumably, we shall compile several times, we would - like to run our test suite, and finally remove all files that can be - re-generated from source. Enter: <filename>Makefile</filename>. + Good, but not good enough! Presumably, we shall compile several + times, so we would like to run our test suite and finally remove + all files that can be re-generated from source. Enter: + <filename>Makefile</filename>. </para> <example id = "ex-simple-oct-makefile"> @@ -491,11 +477,10 @@ .phony: test test: matpow.oct - octave --silent testmp.m - + octave --silent test_matpow.m -matpow.oct: matpow.cc - mkoctfile matpow.cc +%.oct: %.cc + mkoctfile $< </programlisting> </example> </sect3> @@ -505,15 +490,14 @@ <para> If the <filename>oct</filename>-file is in the <envar>LOADPATH</envar>, it - will be loaded automatically the first time Octave hits the undefined - symbol, either through a call to <command>help</command>, or through a - function invocation. + will be loaded automatically – either when requesting + <command>help</command> on the function or when invoking it directly. </para> <screen> -<prompt>cspiel@hydra$</prompt> <userinput>ls</userinput> -Makefile matpow.cc matpow.o matpow.oct matrix-power.m testmp.m -<prompt>cspiel@hydra$</prompt> <userinput>octave -q</userinput> +<prompt>$</prompt> <userinput>ls</userinput> +Makefile matpow0.m matpow1.m matpow.cc matpow.o matpow.oct test_matpow.m +<prompt>$</prompt> <userinput>octave -q</userinput> <prompt>octave:1></prompt> <userinput>help matpow</userinput> matpow is the dynamically-linked function from the file /home/cspiel/hsc/octave/src/matpow/matpow.oct
--- a/doc/coda/oct/tut-interm.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/oct/tut-interm.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,5 +1,6 @@ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -26,32 +27,32 @@ <para> The keen reader will have noticed that <function>matpow</function> is highly vulnerable to unexpected input. We take care of this deficiency in - <xref linkend = "sect-oct-tutorial-spice-input-check"></xref>. Next, the - documentation too is not ready for prime time, something that changes in - <xref linkend = "sect-oct-tutorial-spice-texinfo"></xref>. + <xref linkend = "sect-oct-tutorial-spice-input-check"></xref>. + Also, the documentation is not ready for prime time, something we + attend to in <xref linkend = "sect-oct-tutorial-spice-texinfo"></xref>. </para> <sect3 id = "sect-oct-tutorial-spice-input-check"> <title>Input parameter checking</title> <para> - Why do we need parameter checking at all? The rule of thumb recommends to + Why do we need parameter checking at all? A rule of thumb is to perform a <emphasis>complete</emphasis> parameter checking on </para> <itemizedlist> <listitem> <para> - every function that is exposed to the user (e.g., at Octave's - interpreter level), i.e., for every function created with <symbol + every function that is exposed to the user (e.g. at Octave's + interpreter level), i.e. for every function created with <symbol role = "macro">DEFUN_DLD</symbol>, or </para> </listitem> <listitem> <para> - any function that might be used in a different context that the - writer has thought of. Functions that are used only internally, do + any function that might be used in a different context than the + writer intended Functions that are used only internally do not require full parameter checking. </para> </listitem> @@ -60,8 +61,8 @@ <para> One problem which arises frequently with parameter checking of (interfacing) functions is that the checks easily take up more space than - the routine itself, thereby distracting the reader of the function's - original purpose. Often, including all the checks into the worker function + the routine itself, thereby distracting the reader from the function's + original purpose. Often, including all the checks into the main function bloats it beyond the desired maintainability. Therefore, we have to take precautions against these problems by consistently factoring out all parameter checks. @@ -69,9 +70,9 @@ <para> <!-- reference to: Fowler "Refactoring" --> The rule of thumb here is to group logically related tests together in - seperate functions. The testing functions get the original functions' + separate functions. The testing functions get the original functions' arguments <emphasis>by constant reference</emphasis> and return a boolean - value. The pass-by-<literal>const T&</literal> avoids any constructor + value. <emphasis>Constant referencing</emphasis> avoids any constructor calls and – in addition to that – protects the arguments against modification. In our example a single test function is enough: </para> @@ -85,9 +86,9 @@ Octave error, and returns <constant>true</constant> if the arguments fail any test; otherwise it returns <constant>false</constant> and we can continue processing. The only thing we have to change in - <function>matpow</function> is add a call to - <function>any_bad_argument</function> and on failure return an Octave-void - value, i.e., an empty <type>octave_value_list</type>. The first few lines + <function>matpow</function> is to add a call to + <function>any_bad_argument</function> and on failure to return an Octave-void + value, i.e. an empty <type>octave_value_list</type>. The first few lines of <function>matpow</function> then take the following form: </para> @@ -164,7 +165,7 @@ Octave supplies the user with all necessary type- and size-testing functions. The type-tests (defined in OCT/src/<filename class = "headerfile">ov-base.h</filename>) share the common - prefix <literal>is_</literal>. + prefix <literal>is_</literal>. Here are the most commonly used: </para> <classsynopsis language = "cpp"> @@ -186,26 +187,6 @@ <methodsynopsis> <modifier>public</modifier> - <type>bool</type> <methodname>is_scalar_type</methodname> - - <void></void> - - <modifier>const</modifier> - </methodsynopsis> - - <methodsynopsis> - <modifier>public</modifier> - - <type>bool</type> <methodname>is_complex_type</methodname> - - <void></void> - - <modifier>const</modifier> - </methodsynopsis> - - <methodsynopsis> - <modifier>public</modifier> - <type>bool</type> <methodname>is_real_scalar</methodname> <void></void> @@ -216,7 +197,17 @@ <methodsynopsis> <modifier>public</modifier> - <type>bool</type> <methodname>is_matrix_type</methodname> + <type>bool</type> <methodname>is_complex_scalar</methodname> + + <void></void> + + <modifier>const</modifier> + </methodsynopsis> + + <methodsynopsis> + <modifier>public</modifier> + + <type>bool</type> <methodname>is_real_matrix</methodname> <void></void> @@ -232,14 +223,12 @@ <modifier>const</modifier> </methodsynopsis> + </classsynopsis> <para> - The size tests, which ought to be called <quote>extension</quote> fro - precision, of course depend on the underlying type. E.g. a list has only a - length (OCT/src/<filename class = "headerfile">ov-list.h</filename>), - whereas a matrix has a number for rows and a number of columns - (OCT/src/<filename class = "headerfile">ov-base-mat.h</filename>). + To examine the sizes of different Octave objects, the following + methods prove useful: </para> <classsynopsis language = "cpp"> @@ -304,19 +293,15 @@ </methodsynopsis> </classsynopsis> -<caution> - <para> - <methodname>octave_base_matrix::length</methodname> has weird - semantics! If either <literal>rows == 0</literal> or <literal>columns - == 0</literal>, it returns 0; otherwise it returns <literal>max(rows, - columns)</literal>. - </para> -</caution> - - +<para> + Remember that the methods available depend on the underlying + type. For example, a ColumnVector only has a length (OCT/src/<filename class = "headerfile">ov-list.h</filename>), + whereas a Matrix has a number of rows and columns + (OCT/src/<filename class = "headerfile">ov-base-mat.h</filename>). +</para> <para> - We have all the knowledge we need to write the argument testing fuction to + We have all the knowledge we need to write the argument testing function to augment <function>matpow</function>. </para> @@ -324,9 +309,9 @@ static bool any_bad_argument(const octave_value_list& args) { - if (!args(0).is_matrix_type()) + if (!args(0).is_real_matrix()) { - error("matpow: expecting base A (arg 1) to be a matrix"); + error("matpow: expecting base A (arg 1) to be a real matrix"); return true; } @@ -364,56 +349,55 @@ </para> <programlisting role = "octave"> -function rv = erreval(try_st, catch_st) - ## erreval() extends the built-in funciton eval(). Return 0 if - ## try_st does not raise an error, return 1 otherwise. erreval() is - ## well suited to check the error exits of a function. - - switch (nargin) - case 1 - eval([try_st, "; rv = 0;"], "rv = 1;"); - case 2 - eval([try_st, "; rv = 0;"], [catch_st, "; rv = 1;"]); - otherwise - error("expecting 1 or 2 arguments"); - endswitch -endfunction - ### ### The following tests should trigger the error exits. ### - ## number of arguments -unittest("error exit, too few arguments", 1, erreval("matpow()")); -unittest("error exit, too few arguments", 1, - erreval("matpow([1, 1; 1, 1])")); -unittest("error exit, too many arguments", 1, - erreval("matpow([1, 1; 1, 1], 2, 1)")); +unit_test_err("error exit, too few arguments", + "matpow:", "matpow([1,1; 1,1])"); + +unit_test_err("error exit, too few arguments", + "matpow:", "matpow()"); + +unit_test_err("error exit, too many arguments", + "matpow:", "matpow([1,1; 1 1], 2, 1)"); ## argument type and size + +unit_test_err("error exit, A not a matrix", + "matpow:", "matpow(1, 1)"); + +unit_test_err("error exit, A not a square matrix", + "matpow:", "matpow([1 2 3; 4 5 6], 1)"); + +unit_test_err("error exit, N not a real scalar(here: complex)", + "matpow:", "matpow(a, 1+i)"); + +unit_test_err("error exit, N not a real scalar(here: non-scalar)", + "matpow:", "matpow(a, ones(2,2))"); + +unit_test_err("error exit, N negative", + "matpow:", "matpow(a, -1)"); + +unit_test_err("error exit, N non-integral", + "matpow:", "matpow(2.5)"); -unittest("error exit, A not a matrix", 1, erreval("matpow(1, 1)")); -unittest("error exit, A not a square matrix", 1, - erreval("matpow([1, 2, 3; 4, 5, 6], 1)")); -unittest("error exit, N not a real scalar (here: complex)", 1, - erreval("matpow(a, 1+i)")); -unittest("error exit, N not a real scalar (here: real non-scalar)", 1, - erreval("matpow(a, ones(2, 2))")); -unittest("error exit, N negative", 1, erreval("matpow(a, -1)")); -unittest("error exit, N non-integral", 1, erreval("matpow(a, 2.5)")); </programlisting> <screen> -<prompt>cspiel@hydra$</prompt> <userinput>octave -q testmp.m</userinput> +<prompt>$</prompt> <userinput>octave -q test_matpow.m</userinput> +................ # of testcases attempted 16 # of expected passes 16 # of expected failures 0 # of unexpected passes 0 # of unexpected failures 0 # of unresolved testcases 0 + +Unit testing completed successfully! </screen> </sect3> @@ -439,7 +423,7 @@ <para> The fundamental building block of Texinfo documentation strings is the Texinfo-macro <literal>@deftypefn</literal>, which takes two - arguments: The class the function is in, and the function's signature. FOr + arguments: The class the function is in, and the function's signature. For functions defined with <literal>DEFUN_DLD</literal>, the class is <literal>Loadable Function</literal>. A skeletal Texinfo docstring therefore looks like this: @@ -469,7 +453,7 @@ <para> <literal>@deftypefn{<replaceable>class</replaceable>} ... @end deftypefn</literal> encloses the whole doc-string, like a LaTeX - environment, or a DocBook element does. + environment or a DocBook element does. </para> </callout> @@ -489,7 +473,7 @@ <literal>@var{<replaceable>variable_name</replaceable>}</literal>, and <literal>@code{<replaceable>code_piece</replaceable>}</literal>. The Texinfo format has been designed to generate output for online viewing with - text-terminals as well as generating high-quality printed output. To this + text-terminals as well as generating high-quality printed output. To these ends, Texinfo has commands which control the diversion of parts of the document into a particular output processor. Two formats are of importance: info and TeX. The first is selected with @@ -531,7 +515,7 @@ @cindex matrix power Return matrix @var{a} raised to the @var{n}-th power. Matrix @var{a} is -a square matrix, and @var{n} a non-negative integer. +a square matrix and @var{n} a non-negative integer. @iftex <co id = "co-texi-iftex"></co> @tex <co id = "co-texi-tex"></co> $n = 0$ @@ -540,7 +524,7 @@ @ifinfo <co id = "co-texi-ifinfo"></co> n = 0 @end ifinfo -is explicitely allowed, returning a unit-matrix of the same size as +is explicitly allowed, returning a unit-matrix of the same size as @var{a}. Note: @code{matpow} <co id = "co-texi-code"></co> duplicates part of the functionality of the built-in @@ -623,17 +607,17 @@ <para> For further information about Texinfo consult the Texinfo documentation. - For TeX-beginners, we recommend <quote>The Not So Short Introduction to - LaTeX</quote> by Tobias Oetiker et al. + For TeX-beginners we recommend <quote>The Not So Short Introduction to + LaTeX</quote> by Tobias Oetiker et. al. </para> <para> - One thing we held back is the <emphasis></emphasis> true apperance of a + One thing we held back is the <emphasis></emphasis> true appearance of a Texinfo docstring – mainly because it looks so ugly. The C++-language imposes the constraint that the docstring must be a string-constant. Moreover, because <literal>DEFUN_DLD</literal> is a macro, every line-end has to be escaped with a backslash. The backslash - does not insert any whitespace and TeX seperates paragrphas with empty + does not insert any whitespace and TeX separates paragraphs with empty lines, so that we have to put in new-lines as line-separators. Thus, the Texinfo docstring in source form has each line end decorated with <quote><literal>\n\</literal></quote>. @@ -642,7 +626,7 @@ <programlisting role = "c++"> DEFUN_DLD(matpow, args, , "-*- texinfo -*-\n\ -@deftypefn{Loadable Function} @var{b} = matpow(@var{a}, @var{n})\n\ +@deftypefn{Loadable Function} {@var{b}} = matpow(@var{a}, @var{n})\n\ \n\ @cindex matrix power\n\ \n\ @@ -685,7 +669,7 @@ <mediaobject> <imageobject> - <imagedata fileref = "matpow.eps" format = "EPS"></imagedata> + <imagedata fileref = "matpow" format = "EPS"></imagedata> </imageobject> <imageobject>
--- a/doc/coda/oct/tut-intro.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/oct/tut-intro.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,5 +1,6 @@ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -25,7 +26,7 @@ <para> Instead of giving an abstract treatise, we want to explain the whole - business if dynamical extensions with the help of a simple, yet non-trivial + business of dynamical extensions with the help of a simple, yet non-trivial problem. This example shall be analyzed in detail from beginning to end, and we shall elucidate some modern software construction principles on the way. @@ -45,8 +46,8 @@ </para> <para> - Boundary cases, we have to watch out for: an empty - matrix <replaceable>A</replaceable>, or a zero + We have to watch out for boundary cases: an empty + matrix <replaceable>A</replaceable> or a zero exponent <replaceable>n</replaceable>. </para> </sect2> @@ -81,7 +82,7 @@ <programlisting role = "octave"> function b = matpow0(a, n) ## Return b = a^n for square matrix a, and non-negative, integral n. - ## Note: matpow0() has an extremely naive implementation. + ## Note: matpow0() is an extremely naive implementation. b = diag(ones(size(a, 1), 1)); for i = 1:n @@ -93,56 +94,41 @@ <para> Easy does the job! <function>matpow0</function> looks like it does what we - want, but how can we be sure? We write a test-suite! A test-suite is - needed anyhow when we switch to C++. We have a piece of running code, so + want, but how can we be sure? We write a test-suite<footnote><para> + Octave-forge contains a good unit testing framework. The framework + provided here is very simple and only intended as a teaching aid. + </para></footnote>! A test-suite is + needed when we switch to C++. We have a piece of running code, so let us write some tests. The unit testing functions are defined in <xref - linkend = "app-examples"></xref>, <xref linkend = - "sect-ex-unittest"></xref>. + linkend = "app-examples"></xref>, <xref linkend = "sect-ex-unittest"></xref>. </para> <programlisting role = "octave"> -### name: testmp.m -- test matrix power functions -### author: Ch. L. Spiel -### last rev.: Fri Feb 23 10:00:15 UTC 2001 -### Octave ver.: 2.1.33 - -1; - - -function eq = mat_equal(m1, m2) - ## Return 1 if every element of matrix m1 is equal to the - ## corresponding element in matrix m2, i.e., if m1 == m2; return 0 - ## otherwise. - - eq = any(any(m1 == m2)); -endfunction - +### name: test_matpow.m -- test matrix power functions +### original: Ch. L. Spiel ### ### The following tests should succeed. ### - -<link linkend = "sect-ex-unittest-initunittest-m">initunittest</link>(); +<link linkend = "sect-ex-unittest-unit_init-m">unit_init</link>(0, {"a"}); ## Quiet testing, use global variable a a = [ 2.0, -3.0; -1.0, 1.0]; -<link linkend = "sect-ex-unittest-unittest-m">unittest</link>("a^0", 1, eval("mat_equal(matpow(a, 0), diag([1, 1]))")); -<link linkend = "sect-ex-unittest-unittest-m">unittest</link>("a^1", 1, eval("mat_equal(matpow(a, 1), a)")); -<link linkend = "sect-ex-unittest-unittest-m">unittest</link>("a^2", 1, eval("mat_equal(matpow(a, 2), a^2)")); -<link linkend = "sect-ex-unittest-unittest-m">unittest</link>("a^3", 1, eval("mat_equal(matpow(a, 3), a^3)")); -<link linkend = "sect-ex-unittest-unittest-m">unittest</link>("a^4", 1, eval("mat_equal(matpow(a, 4), a^4)")); -<link linkend = "sect-ex-unittest-unittest-m">unittest</link>("a^22", 1, eval("mat_equal(matpow(a, 22), a^22)")); -<link linkend = "sect-ex-unittest-unittest-m">unittest</link>("a^23", 1, eval("mat_equal(matpow(a, 23), a^23)")); - +<link linkend = "sect-ex-unittest-unit_test-m">unit_test_equals</link>("a^0", matpow0(a, 0), diag([1, 1])); +<link linkend = "sect-ex-unittest-unit_test-m">unit_test_equals</link>("a^1", matpow0(a, 1), a); +<link linkend = "sect-ex-unittest-unit_test-m">unit_test_equals</link>("a^2", matpow0(a, 2), a^2); +<link linkend = "sect-ex-unittest-unit_test-m">unit_test_equals</link>("a^3", matpow0(a, 3), a^3); +<link linkend = "sect-ex-unittest-unit_test-m">unit_test_equals</link>("a^4", matpow0(a, 4), a^4); +<link linkend = "sect-ex-unittest-unit_test-m">unit_test_equals</link>("a^22", matpow0(a, 22), a^22); +<link linkend = "sect-ex-unittest-unit_test-m">unit_test_equals</link>("a^23", matpow0(a, 23), a^23); ### ### print results ### - -<link linkend = "sect-ex-unittest-prunittest-m">prunittest</link>(); +<link linkend = "sect-ex-unittest-unit_results-m">unit_results</link>(); </programlisting> <para> @@ -150,7 +136,8 @@ </para> <screen> -<prompt>octave:2></prompt> <userinput>testmp</userinput> +<prompt>octave:2></prompt> <userinput>test_matpow</userinput> +................ # of testcases attempted 7 # of expected passes 7 # of expected failures 0 @@ -181,20 +168,22 @@ <para> If the exponent <replaceable>n</replaceable> is a - <replaceable>w</replaceable>-bit number, we can apply the binary - expansion <replaceable>n</replaceable> = + <replaceable>w</replaceable>-bit number, we can apply the + binary expansion <replaceable>n</replaceable> = sum(<replaceable>b<subscript>i</subscript></replaceable> * 2<superscript><replaceable>i</replaceable></superscript>, - <replaceable>i</replaceable> = 0..<replaceable>w</replaceable>-1), - where the <replaceable>b<subscript>i</subscript></replaceable> are - either 0 or 1. In other words, we square <replaceable>A</replaceable> - and its squares for every 1 in the binary expansion of - <replaceable>n</replaceable>, adding this partial sum to the final - result. Special care has to be taken for the cases where + <replaceable>i</replaceable> = + 0..<replaceable>w</replaceable>-1), where the + <replaceable>b<subscript>i</subscript></replaceable> are + either 0 or 1. In other words, we square + <replaceable>A</replaceable> for every bit in the binary + expansion of <replaceable>n</replaceable>, multiplying this + value with the final result if + <replaceable>b<subscript>i</subscript></replaceable> = 1. + Special care has to be taken for the cases where <replaceable>n</replaceable> = 0 or 1. See also - <citation>Golub:1996</citation>, section 11.2.5, page 569. - </para> -</formalpara> + <citation>Golub:1996</citation>, section 11.2.5, + page 569. </para> </formalpara> <example id = "ex-matpow-high-level"> <title>Implementation of improved matrix power algorithm</title>
--- a/doc/coda/oct/tutorial.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/oct/tutorial.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -26,9 +26,9 @@ <para> The tutorial unfurls slowly; we do not want to scare anybody by the complexity of the task ahead. At any time, if you feel like it, look into - the directories OCT<filename class = "directory">/src</filename>, or + the directories OCT<filename class = "directory">/src</filename> or OCT<filename class = "directory">/src/DLD-FUNCTIONS</filename>, where OCT - is the root directory of your Octave source-tree, and consult the + is the root directory of your Octave source-tree and consult the header-files and already existent dynamic extensions. </para>
--- a/doc/coda/standalone/standalone.sgml Fri Feb 06 20:34:57 2004 +0000 +++ b/doc/coda/standalone/standalone.sgml Mon Feb 09 16:16:19 2004 +0000 @@ -1,5 +1,6 @@ <!-- Copyright (C) 2001 Christoph L. Spiel + Copyright (C) 2004 Stefan van der Walt <stefan@sun.ac.za> This file is part of "Da Coda Al Fine". @@ -35,7 +36,7 @@ <para> The libraries Octave itself uses, can be utilized in standalone applications. These applications then have access, for example, to the - vector and matrix classes as well to all algorithms of Octave. + vector and matrix classes as well as to all the Octave algorithms. </para> <para> @@ -75,135 +76,19 @@ </example> <para> - The difficulty in our example is not the C++-code, but the - <filename>Makefile</filename> that correctly builds the application. - <xref linkend = "ex-hello-world-makefile"></xref> shows a - <filename>Makefile</filename> that accomplishes the task. -</para> + <filename>mkoctfile</filename> can once again be used to + compile our application: -<para> - To compile and link <filename>hello.cc</filename> the place where Octave - has been installed must be known (<varname role = - "Makefile">prefix</varname>). The makefile will find out most of the other - important parameters like, for example, the version number of Octave. - Variable <varname role = "Makefile">LDLIBS</varname> deserves a closer - look. It lists all three main libraries (octave, octinterp, and cruft) as - well as the library used for searching m-files, kpathsea. If Octave has - been linked against more libraries (for example Blas, Lapack, or HDF5), or - the standalone application needs further libraries, they can be added here. - The auxiliary variable <varname role = "Makefile">lib_dir</varname> - assumes that the kpathsea-library is installed in Octave's library - directory. Note that the default installation <emphasis>does - not</emphasis> install kpathsea! So, either the installation must be done - manually, or a path to kpathsea must be supplied. +<screen> +<prompt>$</prompt> <userinput>mkoctfile --link-stand-alone hello.cc -o hello</userinput> +<prompt>$</prompt> <userinput>./hello</userinput> +<computeroutput> +Hello Octave world! + 11 12 + 21 22 +</computeroutput> +<prompt>$</prompt> +</screen> </para> -<example id = "ex-hello-world-makefile"> - <title> - <filename>Makefile</filename> for <quote>Hello World!</quote> program. - </title> - - <programlisting role = "makefile"> -# $(prefix) points to the *installation* root, not the build root. -# Most folks will have '/usr' or '/usr/local' in the next line. -prefix:=/site - -octave_version:=$(shell octave -v | sed -ne 's/^.*version \([^ ]*\) .*$$/\1/p') -octave_dir:=octave-$(octave_version) - -includes:=-I$(prefix)/include/$(octave_dir) \ - -I$(prefix)/include/$(octave_dir)/octave - -# We could substitute '$(shell mkoctfile -p CXX)' for 'g++' -CXX:=g++ - -# As above '$(shell mkoctfile -p CXXFLAGS)' would give the options -# Octave was built with. -CXXFLAGS:=-Wall -W -g $(includes) - -LD:=$(CXX) - -lib_dir:=$(prefix)/lib/$(octave_dir) - -LDFLAGS:=-g -Wl,-rpath,$(lib_dir) -L$(lib_dir) - -LDLIBS:=-loctave -loctinterp -lcruft -lkpathsea \ - -ltermcap -lreadline -ldl -lg2c - - -.PHONY: all -all: hello - -.PHONY: clean -clean: - rm -f hello hello.o - -.PHONY: distclean -distclean: clean - rm -f *~ - - -hello: hello.o - $(LD) $(LDFLAGS) -o $@ $^ $(LDLIBS) - -hello.o: hello.cc - $(CXX) $(CXXFLAGS) -c -o $@ $^ - </programlisting> -</example> - -<para> - It is recommended to build the kpathsea-library as shared object. However, - by default Octave <emphasis>disables</emphasis> building a shared kpathsea! - To enable, apply the following patch to - <replaceable>octave_source_directory</replaceable><filename>/kpathsea/acklibtool.m4</filename>. -</para> - -<programlisting role = "unified-diff"> ---- acklibtool.m4 2001/10/19 07:21:38 1.1 -+++ acklibtool.m4 2001/10/19 07:22:34 -@@ -20,18 +20,14 @@ - exit 1 - fi - # --## For use with Octave, ignore these options and only build static libraries. --## --## Argument parsing: we support --enable-shared and --enable-static. --#AC_ARG_ENABLE(shared, --#[ --enable-shared build shared libraries [default=no]],, --# enable_shared=no) --## --#AC_ARG_ENABLE(static, --#[ --enable-static build static libraries [default=yes]],, --# enable_static=yes) --enable_shared=no --enable_static=yes -+# Argument parsing: we support --enable-shared and --enable-static. -+AC_ARG_ENABLE(shared, -+[ --enable-shared build shared libraries [default=no]],, -+ enable_shared=no) -+# -+AC_ARG_ENABLE(static, -+[ --enable-static build static libraries [default=yes]],, -+ enable_static=yes) - # - # If they explicitly --enable-static, make that the link type. - # More commonly, they will just --enable-shared; make that the link type. -</programlisting> - -<para> - then, in the kpathsea source directory, run -</para> - -<programlisting role = "bash"> -autoconf -make distclean -./configure --disable-static --enable-shared -make -cp SHARED/libkpathsea.* <replaceable>your_octave_library_dir</replaceable> -</programlisting> - -<para> - On a 32 bit platform, linking against a shared kpathsea saves - 150-200 KB for each binary. -</para> </chapter>