Mercurial > octave
changeset 2333:b1a56412c385
[project @ 1996-07-19 02:20:16 by jwe]
Initial revision
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/conf.texi.in Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,6 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@set VERSION %OCTAVE_VERSION% +@set OCTAVEHOME %OCTAVE_HOME%
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/faq/FAQ.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,759 @@ +\input texinfo.tex @c -*-texinfo-*- + +@setfilename FAQ.info +@settitle Frequently asked questions about Octave (with answers) + +@c Smaller amounts of whitespace for the 8.5 by 11 inch format. +@tex +\global\chapheadingskip = 15pt plus 4pt minus 2pt +\global\secheadingskip = 12pt plus 3pt minus 2pt +\global\subsecheadingskip = 9pt plus 2pt minus 2pt +\global\parskip 5pt plus 1pt + +@finalout +@end tex + +@setchapternewpage off + +@titlepage +@title Octave FAQ +@subtitle Frequently asked questions about Octave +@subtitle December 1, 1994 +@sp 1 +@author John W. Eaton +@page +@end titlepage + +@ifinfo +@node Top, What is Octave?, (dir), (dir) +@top +@unnumbered Preface +@cindex FAQ for Octave, latest version +@end ifinfo + +This is a list of frequently asked questions (FAQ) for Octave users. + +Some information in this FAQ was developed for earlier versions of +Octave and may now be obsolete. + +I'm looking for new questions (@emph{with} answers), better answers, +or both. Please send suggestions to bug-octave@@bevo.che.wisc.edu. +If you have general questions about Octave, or need help for something +that is not covered by the FAQ, please use the +help-octave@@bevo.che.wisc.edu mailing list. + +This FAQ is intended to supplement, not replace, the Octave manual. +Before posting a question to the hlpe-octave mailing list, you should +first check to see if the topic is covered in the manual. + +@menu +* What is Octave?:: +* Version 1.1.0:: +* Octave Features:: +* Documentation:: +* Getting Octave:: +* Installation:: +* Common problems:: +* Getting additional help:: +* Bug reports:: +* MATLAB compatibility:: +* Index:: +@end menu + +@node What is Octave?, Version 1.1.0, Top, Top +@chapter What is Octave? + +Octave is a high-level interactive language, primarily intended for +numerical computations that is mostly compatible with +@sc{Matlab}.@footnote{@sc{Matlab} is a registered trademark of The MathWorks, +Inc.} + +Octave can do arithmetic for real and complex scalars and matrices, +solve sets of nonlinear algebraic equations, integrate functions over +finite and infinite intervals, and integrate systems of ordinary +differential and differential-algebraic equations. + +Octave uses the GNU readline library to handle reading and editing +input. By default, the line editing commands are similar to the +cursor movement commands used by GNU Emacs, and a vi-style line +editing interface is also available. At the end of each session, the +command history is saved, so that commands entered during previous +sessions are not lost. + +The Octave distribution includes a 200+ page Texinfo manual. Access +to the complete text of the manual is available via the help command +at the Octave prompt. + +Two and three dimensional plotting is fully supported using gnuplot. + +The underlying numerical solvers are currently standard Fortran ones +like Lapack, Linpack, Odepack, the Blas, etc., packaged in a library +of C++ classes. If possible, the Fortran subroutines are compiled +with the system's Fortran compiler, and called directly from the C++ +functions. If that's not possible, you can still compile Octave if +you have the free Fortran to C translator f2c. + +Octave is also free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation. + +@node Version 1.1.0, Octave Features, What is Octave?, Top +@chapter What's new in version 1.1.0 of Octave + +The long-awaited version 1.1.0 of Octave has now been released. Many +bugs have been fixed and lots of new features added. Octave is now much +more compatible with @sc{Matlab}. + +Version 1.1.0 fixes many bugs, but as with any ``x.y.0'' release there +will be a few glitches. You can expect a 1.1.1 shortly. You can help +contribute to the quality of Octave by trying it out and submitting bug +reports where you find them. + +A list of user-visible changes in recent versions of Octave may be found +in the file NEWS, distributed in both source and binary releases of +Octave. + +@node Octave Features, Documentation, Version 1.1.0, Top +@chapter What features are unique to Octave? + +@menu +* Command and variable name completion:: +* Command history:: +* Data structures:: +* Short-circuit boolean operators:: +* Increment and decrement operators:: +* Unwind-protect:: +* Variable-length argument lists:: +* Variable-length return lists:: +* Built-in ODE and DAE solvers:: +@end menu + +@node Command and variable name completion, Command history, Octave Features, Octave Features +@section Command and variable name completion + +@cindex Command completion +@cindex Function name completion +@cindex Variable name completion +@cindex Name completion + +Typing a TAB character (ASCII code 9) on the command line causes Octave +to attempt to complete variable, function, and file names. Octave uses +the text before the cursor as the initial portion of the name to +complete. + +For example, if you type @samp{fu} followed by TAB at the Octave prompt, +Octave will complete the rest of the name @samp{function} on the command +line (unless you have other variables or functions defined that begin +with the characters @samp{fu}). If there is more than one possible +completion, Octave will ring the terminal bell to let you know that your +initial sequence of characters is not enough to specify a unique name. +To complete the name, you may either edit the initial character sequence +(usually adding more characters until completion is possible) or type +another TAB to cause Octave to display the list of possible completions. + +@node Command history, Data structures, Command and variable name completion, Octave Features +@section Command history + +@cindex Command history +@cindex History + +When running interactively, Octave saves the commands you type in an +internal buffer so that you can recall and edit them. Emacs and vi +editing modes are available with Emacs keybindings enabled by default. + +When Octave exits, the current command history is saved to the file +@file{~/.octave_hist}, and each time Octave starts, it inserts the +contents of the @file{~/.octave_hist} file in the history list so that +it is easy to begin working where you left off. + +@node Data structures, Short-circuit boolean operators, Command history, Octave Features +@section Data structures + +@cindex Data structures +@cindex Structures + +Octave includes a limited amount of support for organizing data in +structures. The current implementation uses an associative array +with indices limited to strings, but the syntax is more like C-style +structures. Here are some examples of using data structures in Octave. + +@itemize @bullet +@item Elements of structures can be of any value type. + +@example +octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string"; +octave:2> x.a +x.a = 1 +octave:3> x.b +x.b = + + 1 2 + 3 4 + +octave:4> x.c +x.c = string +@end example + +@item Structures may be copied. + +@example +octave:1> y = x +y = + +<structure: a b c> +@end example + +@item Structure elements may reference other structures. + +@example +octave:1> x.b.d = 3 +x.b.d = 3 +octave:2> x.b +x.b = + +<structure: d> + +octave:3> x.b.d +x.b.d = 3 +@end example + +@item Functions can return structures. + +@example +octave:1> function y = f (x) +> y.re = real (x); +> y.im = imag (x); +> endfunction + +octave:2> f (rand + rand*I); +ans = + +<structure: im re> + +octave:3> ans.im, ans.re +ans.im = 0.93411 +ans.re = 0.56234 +@end example + +@item Function return lists can include structure elements, and they may +be indexed like any other variable. + +@example +octave:1> [x.u, x.s(2:3,2:3), x.v] = svd ([1, 2; 3, 4]) +x.u = + + -0.40455 -0.91451 + -0.91451 0.40455 + +x.s = + + 0.00000 0.00000 0.00000 + 0.00000 5.46499 0.00000 + 0.00000 0.00000 0.36597 + +x.v = + + -0.57605 0.81742 + -0.81742 -0.57605 + +octave:8> x +x = + +<structure: s u v> +@end example + +@item You can also use the function @code{is_struct} to determine +whether a given value is a data structure. For example + +@example +is_struct (x) +@end example + +@noindent +returns 1 if the value of the variable @var{x} is a data structure. +@end itemize + +This feature should be considered experimental, but you should expect it +to work. Suggestions for ways to improve it are welcome. + +@node Short-circuit boolean operators, Increment and decrement operators, Data structures, Octave Features +@section Short-circuit boolean operators + +@cindex Boolean operators, short-circuit +@cindex Logical operators, short-circuit +@cindex Short-circuit boolean operators +@cindex Operators, boolean + +Octave's @samp{&&} and @samp{||} logical operators are evaluated in +a short-circuit fashion (like the corresponding operators in the C +language) and work differently than the element by element operators +@samp{&} and @samp{|}. + +@node Increment and decrement operators, Unwind-protect, Short-circuit boolean operators, Octave Features +@section Increment and decrement operators + +@cindex Increment operators +@cindex Decrement operators +@cindex Operators, increment +@cindex Operators, decrement + +Octave includes the C-like increment and decrement operators @samp{++} +and @samp{--} in both their prefix and postfix forms. + +For example, to pre-increment the variable @var{x}, you would write +@code{++@var{x}}. This would add one to @var{x} and then return the new +value of @var{x} as the result of the expression. It is exactly the +same as the expression @code{@var{x} = @var{x} + 1}. + +To post-increment a variable @var{x}, you would write @code{@var{x}++}. +This adds one to the variable @var{x}, but returns the value that +@var{x} had prior to incrementing it. For example, if @var{x} is equal +to 2, the result of the expression @code{@var{x}++} is 2, and the new +value of @var{x} is 3. + +For matrix and vector arguments, the increment and decrement operators +work on each element of the operand. + +It is not currently possible to increment index expressions. For +example, you might expect that the expression @code{@var{v}(4)++} would +increment the fourth element of the vector @var{v}, but instead it +results in a parse error. This problem may be fixed in a future +release of Octave. + +@node Unwind-protect, Variable-length argument lists, Increment and decrement operators, Octave Features +@section Unwind-protect + +@cindex Unwind-protect + +Octave supports a limited form of exception handling modelled after the +unwind-protect form of Lisp. The general form of an +@code{unwind_protect} block looks like this: + +@example +@group +unwind_protect + @var{body} +unwind_protect_cleanup + @var{cleanup} +end_unwind_protect +@end group +@end example + +@noindent +Where @var{body} and @var{cleanup} are both optional and may contain any +Octave expressions or commands. The statements in @var{cleanup} are +guaranteed to be executed regardless of how control exits @var{body}. + +The @code{unwind_protect} statement is often used to reliably restore +the values of global variables that need to be temporarily changed. + +@node Variable-length argument lists, Variable-length return lists, Unwind-protect, Octave Features +@section Variable-length argument lists + +@cindex Variable-length argument lists +@cindex Argument lists, variable-length + +Octave has a real mechanism for handling functions that take an +unspecified number of arguments, so it is no longer necessary to place +an upper bound on the number of optional arguments that a function can +accept. + +Here is an example of a function that uses the new syntax to print a +header followed by an unspecified number of values: + +@example +function foo (heading, ...) + disp (heading); + va_start (); + while (--nargin) + disp (va_arg ()); + endwhile +endfunction +@end example + +Calling @code{va_start()} positions an internal pointer to the first +unnamed argument and allows you to cycle through the arguments more than +once. It is not necessary to call @code{va_start()} if you do not plan +to cycle through the arguments more than once. + +The function @code{va_arg()} returns the value of the next available +argument and moves the internal pointer to the next argument. It is an +error to call @code{va_arg()} when there are no more arguments +available. + +It is also possible to use the keyword @var{all_va_args} to pass all +unnamed arguments to another function. + +@node Variable-length return lists, Built-in ODE and DAE solvers, Variable-length argument lists, Octave Features +@section Variable-length return lists + +@cindex Variable-length return lists +@cindex Return lists, variable-length + +Octave also has a real mechanism for handling functions that return an +unspecified number of values, so it is no longer necessary to place an +upper bound on the number of outputs that a function can produce. + +Here is an example of a function that uses the new syntax to produce +@samp{N} values: + +@example +function [...] = foo (n) + for i = 1:n + vr_val (i); + endfor +endfunction +@end example + +@node Built-in ODE and DAE solvers, , Variable-length return lists, Octave Features +@section Built-in ODE and DAE solvers + +@cindex DASSL +@cindex LSODE + +Octave includes LSODE and DASSL for solving systems of stiff +differential and differential-algebraic equations. These functions are +built in to the interpreter. + +@node Documentation, Getting Octave, Octave Features, Top +@chapter What documentation exists for Octave? + +@cindex Octave, documentation + +The Octave distribution includes a 220+ page manual that is also +distributed under the terms of the GNU GPL. + +The Octave manual is intended to be a complete reference for Octave, but +it is not a finished document. If you have problems using it, or find +that some topic is not adequately explained, indexed, or +cross-referenced, please send a bug report to bug-octave@@bevo.che.wisc.edu. + +Because the Octave manual is written using Texinfo, the complete text of +the Octave manual is also available on line using the GNU Info system +via the GNU Emacs, info, or xinfo programs, or by using the @samp{help -i} +command to start the GNU info browser directly from the Octave prompt. + +It is also possible to use WWW browsers such as Mosaic to read the +Octave manual (or any other Info file) by using Roar Smith's info2www +program to convert GNU Info files to HTML. The source for info2www is +available via anonymous ftp from ftp.che.wisc.edu in the directory +@file{/pub/www}. + +@node Getting Octave, Installation, Documentation, Top +@chapter Obtaining Source Code + +@cindex Source code + +@menu +* Octave for Unix:: +* Octave for other platforms:: +* latest versions:: +@end menu + +@node Octave for Unix, Octave for other platforms, Getting Octave, Getting Octave +@section How do I get a copy of Octave for Unix? + +You can get Octave from a friend who has a copy, by anonymous FTP, or by +ordering a tape or CD-ROM from the Free Software Foundation (FSF). + +@cindex Octave, ordering +@cindex Octave, getting a copy + +Octave was not developed by the FSF, but the FSF does distribute Octave, +and the developers of Octave support the efforts of the FSF by +encouraging users of Octave to order Octave on tape or CD directly from +the FSF. + +The FSF is a nonprofit organization that distributes software and +manuals to raise funds for more GNU development. Buying a tape or CD +from the FSF contributes directly to paying staff to develop GNU +software. CD-ROMs cost $400 if an organization is buying, or $100 if an +individual is buying. Tapes cost around $200 depending on media type. + +The FSF only makes new CD releases a few times a year, so if you are +interested specifically in Octave, I recommend asking for the latest +release on tape. + +@cindex FSF [Free Software Foundation] +@cindex GNU [GNU's not unix] + +For more information about ordering from the FSF, contact +gnu@@prep.ai.mit.edu, phone (617) 542-5942 or anonymous ftp file +@file{/pub/gnu/GNUinfo/ORDERS} from prep.ai.mit.edu or one of the sites +listed below. + +@cindex FSF, contact <gnu@@prep.ai.mit.edu> +@cindex GNUware, anonymous FTP sites + +If you are on the Internet, you can copy the latest distribution +version of Octave from the file @file{/pub/octave/octave-M.N.tar.gz}, on +the host @file{ftp.che.wisc.edu}. This tar file has been compressed +with GNU gzip, so be sure to use binary mode for the transfer. @samp{M} +and @samp{N} stand for version numbers; look at a listing of the +directory through ftp to see what version is available. After you +unpack the distribution, be sure to look at the files @file{README} and +@file{INSTALL}. + +Binaries for several popular systems are also available. If you would +like help out by making binaries available for other systems, please +contact bug-octave@@bevo.che.wisc.edu. + +A list of user-visible changes since the last release is available in +the file @file{NEWS}. The file @file{ChangeLog} in the source +distribution contains a more detailed record of changes made since the +last release. + +@node Octave for other platforms, latest versions, Octave for Unix, Getting Octave +@section How do I get a copy of Octave for (some other platform)? + +@cindex VMS support +@cindex VAX +@cindex MS-DOS support +@cindex DJGPP +@cindex EMX +@cindex OS/2 support + +Octave currently runs on Unix-like systems only. It should be possible +to make Octave work on other systems. If you are interested in porting +Octave to other systems, please contact bug-octave@@bevo.che.wisc.edu. + +@node latest versions, , Octave for other platforms, Getting Octave +@section What is the latest version of Octave + +@cindex Octave, version date + +The latest version of Octave is 1.1.0, released January 1995. + +@node Installation, Common problems, Getting Octave, Top +@chapter Installation Issues and Problems + +@cindex Octave, building + +Octave requires approximately 50MB of disk storage to unpack and +install (significantly less if you don't compile with debugging +symbols). + +Octave has been compiled and tested with g++ and libg++ on a +SPARCstation 2 running SunOS 4.1.2, an IBM RS/6000 running AIX 3.2.5, +DEC Alpha systems running OSF/1 1.3 and 3.0, a DECstation 5000/240 +running Ultrix 4.2a, and i486 systems running Linux. It should work on +most other Unix systems that have a working port of g++ and libg++. + +@menu +* What else do I need?:: +* Other C++ compilers?:: +@end menu + +@node What else do I need?, Other C++ compilers?, Installation, Installation +@section What else do I need? + +@cindex GNU gcc +@cindex GNU g++ +@cindex libg++ +@cindex GNU Make +@cindex Flex +@cindex GNU Bison + + In order to build Octave, you will need a current version +of g++, libg++, and GNU make. If you don't have these tools, you can +get them from many anonymous ftp archives, including ftp.che.wisc.edu, +ftp.uu.net, prep.ai.mit.edu, and wuarchive.wustl.edu, or by writing to +the FSF at 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +@node Other C++ compilers?, , What else do I need?, Installation +@section Can I compile Octave with another C++ compiler? + +Currently, Octave can only be compiled with the GNU C++ compiler. It +would be nice to make it possible to compile Octave with other C++ +compilers, but the maintainers do not have sufficient time to devote to +this. If you are interested in working to make Octave portable to other +compilers, please contact bug-octave@@bevo.che.wisc.edu. + +@node Common problems, Getting additional help, Installation, Top +@chapter Common problems + +This list is probably far too short. Feel free to suggest additional +questions (preferably with answers!) + +@itemize @bullet +@item +Octave takes a long time to find symbols. + +Octave is probably spending this time recursively searching directories +for function files. Check the value of your LOADPATH. For those +elements that end in @samp{//}, do any name a very large directory tree? +Does it contain directories that have a mixture of files and +directories? In order for the recursive directory searching code to +work efficiently, directories that are to be searched recursively should +have either function files only, or subdirectories only, but not a +mixture of both. Check to make sure that Octave's standard set of +function files is installed this way. +@end itemize + +@node Getting additional help, Bug reports, Common problems, Top +@chapter Getting additional help + +@cindex Additional help +@cindex Mailing lists, help-octave + +The mailing list + +@example +help-octave@@bevo.che.wisc.edu +@end example + +@noindent +is available for questions related to using, installing, and porting +Octave that are not adequately answered by the Octave manual or by this +document. + +If you would like to join the discussion and receive all messages sent +to the list, please send a short note to + +@example +help-octave-request@@bevo.che.wisc.edu + ^^^^^^^ +@end example + +@strong{Please do not} send requests to be added or removed from the the +mailing list, or other administrative trivia to the list itself. + +An archive of old postings to the help-octave mailing list is maintained +on ftp.che.wisc.edu in the directory @file{/pub/octave/MAILING-LISTS}. + +@node Bug reports, MATLAB compatibility, Getting additional help, Top +@chapter I think I have found a bug in Octave. + +@cindex Bug in Octave, newly found + +``I think I have found a bug in Octave, but I'm not sure. How do I know, +and who should I tell?'' + +@cindex Manual, for Octave + +First, see the section on bugs and bug reports in the Octave manual. +The Octave manual is included in the Octave distribution. + +When you report a bug, make sure to describe the type of computer you +are using, the version of the operating system it is running, and the +version of Octave that you are using. Also provide enough code so that +the Octave maintainers can duplicate your bug. + +If you have Octave working at all, the easiest way to do this is to use +the Octave function @code{bug_report}. When you execute this function, +Octave will prompt you for a subject and then invoke the editor on a +file that already contains all the configuration information. When you +exit the editor, Octave will mail the bug report for you. + +@cindex Octave bug report +@cindex Mailing lists, bug-octave + +If for some reason you cannot use Octave's @code{bug_report} function, +mail your bug report to "bug-octave@@bevo.che.wisc.edu". Your message +needs to include enough information to allow the maintainers of Octave +to fix the bug. Please read the section on bugs and bug reports in the +Octave manual for a list of things that should be included in every bug +report. + +@node MATLAB compatibility, Index, Bug reports, Top +@chapter Porting programs from @sc{Matlab} to Octave + +@cindex @sc{Matlab} compatibility +@cindex Compatibility with @sc{Matlab} + +``I wrote some code for @sc{Matlab}, and I want to get it running under +Octave. Is there anything I should watch out for?'' + +The differences between Octave and @sc{Matlab} typically fall into one of +three categories: + +@enumerate +@item +Irrelevant. + +@item +Known differences, perhaps configurable with a user preference variable. + +@item +Unknown differences. +@end enumerate + +The first category, irrelevant differences, do not affect computations +and most likely do not affect the execution of function files. Some +examples are: + +When typing @samp{help function}, Octave displays the first set of +comment lines @emph{after} the function declaration, but @sc{Matlab} +the first set of comment lines starting from the beginning of the file. + +The differences of the second category are usually because the authors +of Octave decided on a better (subjective) implementation that the way +@sc{Matlab} does it, and so introduced ``user preference variables'' so that +you can customize Octave's behavior to be either @sc{Matlab}-compatible or +to use Octave's new features. To make Octave more @sc{Matlab}-compatible, +put the following statements in your @file{~/.octaverc} file. This is a +partial list of the user preference variables that should be changed to +get @sc{Matlab}-compatible behavior. (It is partial because not all the +differences are currently known, and when they become known, this +document lags behind.) + +@example + PS1 = '>> '; + PS2 = ''; + default_save_format = 'mat-binary'; + define_all_return_values = 'true'; + do_fortran_indexing = 'true'; + empty_list_elements_ok = 'true'; + implicit_str_to_num_ok = 'true'; + ok_to_lose_imaginary_part = 'true'; + page_screen_output = 'false'; + prefer_column_vectors = 'false'; + prefer_zero_one_indexing = 'true'; + print_empty_dimensions = 'false'; + treat_neg_dim_as_zero = 'true'; + warn_function_name_clash = 'false'; + whitespace_in_literal_matrix = 'traditional'; +@end example + +Some other known differences are: + +@itemize @bullet +@item +String subscripting is not yet implemented in Octave. For example, + +@example +a = 'reknob'; +a([6,1,5,3,2,4]) +@end example + +@noindent +returns the string @samp{broken} in @sc{Matlab}, but generates an error in +Octave. A future release of Octave will fix this along with providing +a much more complete and powerful set of functions for manipulating strings. + +@item +The Octave plotting functions are mostly compatible with the ones from +@sc{Matlab} 3.x, but not from @sc{Matlab} 4.x. + +@item +The C-style I/O functions are not completely compatible. It would be +useful for someone to explore the differences so that they might be +fixed, or at least noted in the manual. +@end itemize + +The third category of differences is (hopefully) shrinking. If you find +a difference between Octave behavior and @sc{Matlab}, then you should send a +description of this difference (with code illustrating the difference, +if possible) to bug-octave@@bevo.che.wisc.edu. + +An archive of old postings to the Octave mailing lists is maintained +on ftp.che.wisc.edu in the directory @file{/pub/octave/MAILING-LISTS}. + +@node Index, , MATLAB compatibility, Top +@appendix Concept Index + +@printindex cp + +@page +@contents +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/amuse.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,27 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@cindex amusements +@node Amusements, Emacs, Programming Utilities, Top +@chapter Amusements + +@findex texas_lotto +@cindex lottery numbers +@cindex numbers, lottery +Octave cannot promise that you will actually win the lotto, but it can +pick your numbers for you. The function @code{texas_lotto} will select +six numbers between 1 and 50. + +@findex list_primes +@cindex prime numbers +@cindex numbers, prime +The function @code{list_primes (@var{n})} uses a brute-force algorithm to +compute the first @var{n} primes. + +@findex casesen +@findex flops +@findex exit +@findex quit +Other amusing functions include @code{casesen}, @code{flops}, +@code{sombrero}, @code{exit}, and @code{quit}.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/arith.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,420 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Arithmetic, Linear Algebra, Built-in Variables, Top +@chapter Arithmetic + +Unless otherwise noted, all of the functions described in this chapter +will work for real and complex scalar or matrix arguments. + +@menu +* Utility Functions:: +* Complex Arithmetic:: +* Trigonometry:: +* Sums and Products:: +* Special Functions:: +@end menu + +@node Utility Functions, Complex Arithmetic, Arithmetic, Arithmetic +@section Utility Functions + +The following functions are available for working with complex numbers. +Each expects a single argument, and given a matrix, they work on an +element by element basis. + +@ftable @code +@item ceil (@var{x}) +Return the smallest integer not less than @var{x}. If @var{x} is +complex, return @code{ceil (real (@var{x})) + ceil (imag (@var{x})) * I}. + +@item floor (@var{x}) +Return the largest integer not greater than @var{x}. If @var{x} is +complex, return @code{floor (real (@var{x})) + floor (imag (@var{x})) * I}. + +@item fix (@var{x}) +Truncate @var{x} toward zero. If @var{x} is complex, return +@code{fix (real (@var{x})) + fix (imag (@var{x})) * I}. + +@item round (@var{x}) +Return the integer nearest to @var{x}. If @var{x} is complex, return +@code{round (real (@var{x})) + round (imag (@var{x})) * I}. + +@item sign (@var{x}) +Compute the @dfn{signum} function, which is defined as +@iftex +@tex +$$ +{\rm sign} (@var{x}) = \cases{1,&$x>0$;\cr 0,&$x=0$;\cr -1,&$x<0$.\cr} +$$ +@end tex +@end iftex +@ifinfo + +@example + -1, x < 0; +sign (x) = 0, x = 0; + 1, x > 0. +@end example +@end ifinfo + +For complex arguments, @code{sign} returns @code{x ./ abs (@var{x})}. + +@item exp (@var{x}) +Compute the exponential of @var{x}. To compute the matrix exponential, +see @ref{Linear Algebra}. + +@item gcd (@var{x}, @code{...}) +Compute the greatest common divisor of the elements of @var{x}, or the +list of all the arguments. For example, + +@example +gcd (a1, ..., ak) +@end example + +@noindent +is the same as + +@example +gcd ([a1, ..., ak]) +@end example + +An optional second return value, @var{v} +contains an integer vector such that + +@example +g = v(1) * a(k) + ... + v(k) * a(k) +@end example + +@item lcm (@var{x}, @code{...}) +Compute the least common multiple of the elements elements of @var{x}, or +the list of all the arguments. For example, + +@example +lcm (a1, ..., ak) +@end example + +@noindent +is the same as + +@example +lcm ([a1, ..., ak]). +@end example + +@item log (@var{x}) +Compute the natural logarithm of @var{x}. To compute the matrix logarithm, +see @ref{Linear Algebra}. + +@item log2 (@var{x}) +Compute the base-2 logarithm of @var{x}. + +@item log10 (@var{x}) +Compute the base-10 logarithm of @var{x}. + +@item sqrt (@var{x}) +Compute the square root of @var{x}. To compute the matrix square root, +see @ref{Linear Algebra}. + +@item max (@var{x}) +For a vector argument, return the maximum value. For a matrix argument, +return the maximum value from each column, as a row vector. Thus, + +@example +max (max (@var{x})) +@end example + +@noindent +returns the largest element of @var{x}. + +For complex arguments, the magnitude of the elements are used for +comparison. + +@item min (@var{x}) +Like @code{max}, but return the minimum value. + +@item rem (@var{x}, @var{y}) +Return the remainder of @code{@var{x} / @var{y}}, computed using the +expression + +@example +x - y .* fix (x ./ y) +@end example + +An error message is printed if the dimensions of the arguments do not +agree, or if either of the arguments is complex. +@end ftable + +@node Complex Arithmetic, Trigonometry, Utility Functions, Arithmetic +@section Complex Arithmetic + +The following functions are available for working with complex +numbers. Each expects a single argument. Given a matrix they work on +an element by element basis. + +@ftable @code +@item abs (@var{x}) +Compute the magnitude of @var{x}. + +@item angle (@var{x}) +@itemx arg (@var{x}) +Compute the argument of @var{x}. + +@item conj (@var{x}) +Return the complex conjugate of @var{x}. + +@item imag (@var{x}) +Return the imaginary part of @var{x}. + +@item real (@var{x}) +Return the real part of @var{x}. +@end ftable + +@node Trigonometry, Sums and Products, Complex Arithmetic, Arithmetic +@section Trigonometry + +Octave provides the following trigonometric functions: + +@example +sin asin sinh asinh +cos acos cosh acosh +tan atan tanh atanh + +sec asec sech asech +csc acsc csch acsch +cot acot coth acoth +@end example + +@findex sin +@findex cos +@findex tan +@findex asin +@findex acos +@findex atan +@findex sinh +@findex cosh +@findex tanh +@findex asinh +@findex acosh +@findex atanh +@findex sec +@findex csc +@findex cot +@findex asec +@findex acsc +@findex acot +@findex sech +@findex csch +@findex coth +@findex asech +@findex acsch +@findex acoth + +@noindent +Each of these functions expect a single argument. For matrix arguments, +they work on an element by element basis. For example, the expression + +@example +sin ([1, 2; 3, 4]) +@end example + +@noindent +produces + +@example +ans = + + 0.84147 0.90930 + 0.14112 -0.75680 +@end example + +@findex atan2 +In addition, the function @code{atan2 (@var{y}, @var{x})} computes the +arctangent of @var{y}/@var{x} and uses the signs of the arguments to +determine the quadrant of the result, which is in the range +@iftex +@tex +$\pi$ to $-\pi$. +@end tex +@end iftex +@ifinfo +@code{pi} to -@code{pi}. +@end ifinfo + +@node Sums and Products, Special Functions, Trigonometry, Arithmetic +@section Sums and Products + +@ftable @code +@item sum (@var{x}) +For a vector argument, return the sum of all the elements. For a matrix +argument, return the sum of the elements in each column, as a row +vector. The sum of an empty matrix is 0 if it has no columns, or a +vector of zeros if it has no rows (@pxref{Empty Matrices}). + +@item prod (@var{x}) +For a vector argument, return the product of all the elements. For a +matrix argument, return the product of the elements in each column, as a +row vector. The product of an empty matrix is 1 if it has no columns, +or a vector of ones if it has no rows (@pxref{Empty Matrices}). + +@item cumsum (@var{x}) +Return the cumulative sum of each column of @var{x}. For example, + +@example +cumsum ([1, 2; 3, 4]) +@end example + +@noindent +produces + +@example +ans = + + 1 2 + 4 6 +@end example + +@item cumprod (@var{x}) +Return the cumulative product of each column of @var{x}. For example, + +@example +cumprod ([1, 2; 3, 4]) +@end example + +@noindent +produces + +@example +ans = + + 1 2 + 3 8 +@end example + +@item sumsq (@var{x}) +For a vector argument, return the sum of the squares of all the +elements. For a matrix argument, return the sum of the squares of the +elements in each column, as a row vector. +@end ftable + +@node Special Functions, , Sums and Products, Arithmetic +@section Special Functions + +@ftable @code +@item beta +Returns the Beta function, +@iftex +@tex +$$ + B (a, b) = {\Gamma (a) \Gamma (b) \over \Gamma (a + b)}. +$$ +@end tex +@end iftex +@ifinfo + +@example +beta (a, b) = gamma (a) * gamma (b) / gamma (a + b). +@end example +@end ifinfo + +@item betai (@var{a}, @var{b}, @var{x}) +Returns the incomplete Beta function, +@iftex +@tex +$$ + \beta (a, b, x) = B (a, b)^{-1} \int_0^x t^{(a-z)} (1-t)^{(b-1)} dt. +$$ +@end tex +@end iftex +@ifinfo + +@smallexample + x + / +betai (a, b, x) = beta (a, b)^(-1) | t^(a-1) (1-t)^(b-1) dt. + / + t=0 +@end smallexample +@end ifinfo + +If x has more than one component, both @var{a} and @var{b} must be +scalars. If @var{x} is a scalar, @var{a} and @var{b} must be of +compatible dimensions. + +@item erf +Computes the error function, +@iftex +@tex +$$ + {\rm erf} (z) = {2 \over \sqrt{\pi}}\int_0^z e^{-t^2} dt +$$ +@end tex +@end iftex +@ifinfo + +@smallexample + z + / +erf (z) = (2/sqrt (pi)) | e^(-t^2) dt + / + t=0 +@end smallexample +@end ifinfo + +@item erfc (@var{z}) +Computes the complementary error function, @code{1 - erf (@var{z})}. + +@c XXX FIXME XXX -- this isn't actually distributed with Octave yet. +@c +@c @item erfinv +@c Computes the inverse of the error function. + +@item gamma (@var{z}) +Computes the Gamma function, +@iftex +@tex +$$ + \Gamma (z) = \int_0^\infty t^{z-1} e^{-t} dt. +$$ +@end tex +@end iftex +@ifinfo + +@example + infinity + / +gamma (z) = | t^(z-1) exp (-t) dt. + / + t=0 +@end example +@end ifinfo + +@item gammai (@var{a}, @var{x}) +Computes the incomplete gamma function, +@iftex +@tex +$$ + \gamma (a, x) = {\int_0^x e^{-t} t^{a-1} dt \over \Gamma (a)} +$$ +@end tex +@end iftex +@ifinfo + +@smallexample + x + 1 / +gammai (a, x) = --------- | exp (-t) t^(a-1) dt + gamma (a) / + t=0 +@end smallexample +@end ifinfo + +If @var{a} is scalar, then @code{gammai (@var{a}, @var{x})} is returned +for each element of @var{x} and vice versa. + +If neither @var{a} nor @var{x} is scalar, the sizes of @var{a} and +@var{x} must agree, and @var{gammai} is applied element-by-element. + +@item lgamma +Returns the natural logarithm of the gamma function. +@end ftable +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/audio.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,108 @@ +@c Copyright (C) 1996 John W. Eaton +@c Written by Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at> on 1996/05/14 +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Audio Processing, Input and Output, Image Processing, Top +@chapter Audio Processing + +Octave provides a few functions for dealing with audio data. An audio +`sample' is a single output value from an A/D converter, i.e., a small +integer number (usually 8 or 16 bits), and audio data is just a series +of such samples. It can be characterized by three parameters: the +sampling rate (measured in samples per second or Hz, e.g. 8000 or +44100), the number of bits per sample (e.g. 8 or 16), and the number of +channels (1 for mono, 2 for stereo, etc.). + +There are many different formats for representing such data. Currently, +only the two most popular, @emph{linear encoding} and @emph{mu-law +encoding}, are supported by Octave. There is an excellent FAQ on audio +formats by Guido van Rossum <guido@@cwi.nl> which can be found at any +FAQ ftp site, in particular in the directory +@file{/pub/usenet/news.answers/audio-fmts} of the archive site +@code{rtfm.mit.edu}. + +Octave simply treats audio data as vectors of samples (non-mono data are +not supported yet). It is assumed that audio files using linear +encoding have one of the extensions @file{lin} or @file{raw}, and that +files holding data in mu-law encoding end in @file{au}, @file{mu}, or +@file{snd}. + +The basic functions are as follows. + +@ftable @code +@item lin2mu +If the vector @var{x} represents mono audio data in 8- or 16-bit +linear encoding, @kbd{lin2mu (@var{x})} is the correspoding mu-law +encoding. + +@item mu2lin +If the vector @var{x} represents mono audio data in mu-law encoding, +@code{mu2lin (@var{x} [, @var{bps}])} converts it to linear encoding. +The optional argument @var{bps} specifies whether the input data uses +8 bit per sample (default) or 16 bit. + +@item loadaudio +@kbd{@var{x} = loadaudio (@var{name} [, @var{ext} [, @var{bps}]])} loads +audio data from the file @file{@var{name}.@var{ext}} into the vector +@var{x}. + +The extension @var{ext} determines how the data in the audio file is +interpreted; the extensions @file{lin} (default) and @file{raw} +correspond to linear, the extensions @file{au}, @file{mu}, or @file{snd} +to mu-law encoding. + +The argument @var{bps} can be either 8 (default) or 16, and specifies +the number of bits per sample used in the audio file. + +@item saveaudio +@kbd{saveaudio (@var{name}, @var{x}, [, @var{ext} [, @var{bps}]])} saves +a vector @var{x} of audio data to the file @file{@var{name}.@var{ext}}. +The optional parameters @var{ext} and @var{bps} determine the encoding +and the number of bits per sample used in the audio file (see +@code{loadaudio}); defaults are @file{lin} and 8, respectively. +@end ftable + +The following functions for audio I/O require special A/D hardware and +operating system support. It is assumed that audio data in linear +encoding can be played and recorded by reading from and writing to +@file{/dev/dsp}, and that similarly @file{/dev/audio} is used for mu-law +encoding. This definitely works on Linux systems, and should also work +on Suns. If your hardware is accessed differently, please contact +Andreas Weingessel <Andreas.Weingessel@@ci.tuwien.ac.at>. + +@ftable @code +@item playaudio +@kbd{playaudio (@var{name} [, @var{ext}])} plays the audio file +@file{@var{name}.@var{ext}}. + +@kbd{playaudio (@var{x})} plays the audio data contained in the vector +@var{x}. + +@item record +@kbd{@var{x} = record (@var{sec} [, @var{sampling_rate}])} records +@var{sec} seconds of audio input into the vector @var{x}. The default +value for @var{sampling_rate} is 8000 samples per second, or 8kHz. The +program waits until the @key{ENTER} key is hit, and then immediately +starts to record. + +@item setaudio +@kbd{setaudio ([@var{type}])} displays the current value of the +@var{type} property of your mixer hardware. + +@kbd{setaudio ([@var{type} [, @var{value}]])} sets the @var{type} +property to @var{value}. + +For example, if @code{vol} corresponds to the volume property, you can +set it to 50 (percent) by @code{setaudio ("vol", 50)}. + +This is an simple experimental program to control the audio hardware +settings. It assumes that there is a @code{mixer} program which can be +used as @kbd{mixer @var{type} @var{value}}, and simply executes +@kbd{system ("mixer @var{type} @var{value}")}. Future releases might +get rid of this assumption by using the @code{fcntl} interface. +@end ftable + +@c Local Variables: +@c TeX-command-default: "Texinfo" +@c End:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/bugs.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,476 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@c The text of this file will eventually appear in the file BUGS +@c in the Octave distribution, as well as in the Octave manual. + +@ifclear BUGSONLY +@node Trouble, Command Line Editing, Installation, Top +@appendix Known Causes of Trouble with Octave +@end ifclear +@cindex bugs, known +@cindex installation trouble +@cindex known causes of trouble +@cindex troubleshooting + +This section describes known problems that affect users of Octave. Most +of these are not Octave bugs per se---if they were, we would fix them. +But the result for a user may be like the result of a bug. + +Some of these problems are due to bugs in other software, some are +missing features that are too much work to add, and some are places +where people's opinions differ as to what is best. + +@menu +* Actual Bugs:: Bugs we will fix later. +* Reporting Bugs:: +* Bug Criteria:: +* Bug Lists:: +* Bug Reporting:: +* Sending Patches:: +* Service:: +@end menu + +@node Actual Bugs, Reporting Bugs, Trouble, Trouble +@appendixsec Actual Bugs We Haven't Fixed Yet + +@itemize @bullet +@item +Output that comes directly from Fortran functions is not sent through +the pager and may appear out of sequence with other output that is sent +through the pager. One way to avoid this is to force pending output to +be flushed before calling a function that will produce output from +within Fortran functions. To do this, use the command + +@example +fflush (stdout) +@end example + +Another possible workaround is to use the command + +@example +page_screen_output = "false" +@end example + +@noindent +to turn the pager off. + +@item +Control-C doesn't work properly in the pager on DEC Alpha systems +running OSF/1 3.0. + +This appears to be a bug in the OSF/1 3.0 Bourne shell. The problem +doesn't appear on systems running OSF/1 1.3. + +@item +If you get messages like + +@example +Input line too long +@end example + +when trying to plot many lines on one graph, you have probably generated +a plot command that is too larger for @code{gnuplot}'s fixed-length +buffer for commands. Splitting up the plot command doesn't help because +replot is implemented in gnuplot by simply appending the new plotting +commands to the old command line and then evaluating it again. + +You can demonstrate this `feature' by running gnuplot and doing +something like + +@example + plot sin (x), sin (x), sin (x), ... lots more ..., sin (x) +@end example + +@noindent +and then + +@example + replot sin (x), sin (x), sin (x), ... lots more ..., sin (x) +@end example + +@noindent +after repeating the replot command a few times, gnuplot will give you +an error. + +Also, it doesn't help to use backslashes to enter a plot command over +several lines, because the limit is on the overall command line +length, once the backslashed lines are all pasted together. + +Because of this, Octave tries to use as little of the command-line +length as possible by using the shortest possible abbreviations for +all the plot commands and options. Unfortunately, the length of the +temporary file names is probably what is taking up the most space on +the command line. + +You can buy a little bit of command line space by setting the +environment variable @code{TMPDIR} to be "." before starting Octave, or +you can increase the maximum command line length in gnuplot by changing +the following limits in the file plot.h in the gnuplot distribution and +recompiling gnuplot. + +@example +#define MAX_LINE_LEN 32768 /* originally 1024 */ +#define MAX_TOKENS 8192 /* originally 400 */ +@end example + +Of course, this doesn't really fix the problem, but it does make it +much less likely that you will run into trouble unless you are putting +a very large number of lines on a given plot. + +@item +String handling could use some work. +@end itemize + +A list of ideas for future enhancements is distributed with Octave. See +the file @file{PROJECTS} in the top level directory in the source +distribution. + +@node Reporting Bugs, Bug Criteria, Actual Bugs, Trouble +@appendixsec Reporting Bugs +@cindex bugs +@cindex reporting bugs + +Your bug reports play an essential role in making Octave reliable. + +When you encounter a problem, the first thing to do is to see if it is +already known. @xref{Trouble}. If it isn't known, then you should +report the problem. + +Reporting a bug may help you by bringing a solution to your problem, or +it may not. In any case, the principal function of a bug report is +to help the entire community by making the next version of Octave work +better. Bug reports are your contribution to the maintenance of Octave. + +In order for a bug report to serve its purpose, you must include the +information that makes it possible to fix the bug. + +@findex bug_report + +If you have Octave working at all, the easiest way to prepare a complete +bug report is to use the Octave function @code{bug_report}. When you +execute this function, Octave will prompt you for a subject and then +invoke the editor on a file that already contains all the configuration +information. When you exit the editor, Octave will mail the bug report +for you. + +@menu +* Bug Criteria:: +* Where: Bug Lists. Where to send your bug report. +* Reporting: Bug Reporting. How to report a bug effectively. +* Patches: Sending Patches. How to send a patch for Octave. +@end menu + +@node Bug Criteria, Bug Lists, Reporting Bugs, Trouble +@appendixsec Have You Found a Bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex core dump +@item +If Octave gets a fatal signal, for any input whatever, that is +a bug. Reliable interpreters never crash. + +@cindex incorrect output +@cindex incorrect results +@cindex results, incorrect +@cindex answers, incorrect +@cindex erroneous results +@cindex wrong answers +@item +If Octave produces incorrect results, for any input whatever, +that is a bug. + +@cindex undefined behavior +@cindex undefined function value +@item +Some output may appear to be incorrect when it is in fact due to a +program whose behavior is undefined, which happened by chance to give +the desired results on another system. For example, the range operator +may produce different results because of differences in the way floating +point arithmetic is handled on various systems. + +@cindex erroneous messages +@cindex incorrect error messages +@cindex error messages, incorrect +@item +If Octave produces an error message for valid input, that is a bug. + +@cindex invalid input +@item +If Octave does not produce an error message for invalid input, that is +a bug. However, you should note that your idea of ``invalid input'' +might be my idea of ``an extension'' or ``support for traditional +practice''. + +@cindex improving Octave +@cindex suggestions +@item +If you are an experienced user of programs like Octave, your suggestions +for improvement are welcome in any case. +@end itemize + +@node Bug Lists, Bug Reporting, Bug Criteria, Trouble +@appendixsec Where to Report Bugs +@cindex bug report mailing lists +@cindex reporting bugs +@cindex bugs, reporting + +@findex bug_report + +If you have Octave working at all, the easiest way to prepare a complete +bug report is to use the Octave function @code{bug_report}. When you +execute this function, Octave will prompt you for a subject and then +invoke the editor on a file that already contains all the configuration +information. When you exit the editor, Octave will mail the bug report +for you. + +If for some reason you cannot use Octave's @code{bug_report} function, +send bug reports for Octave to: + +@example +bug-octave@@bevo.che.wisc.edu +@end example + +@strong{Do not send bug reports to @samp{help-octave}}. Most users of +Octave do not want to receive bug reports. Those that do have asked to +be on @samp{bug-octave}. + +As a last resort, send bug reports on paper to: + +@example +Octave Bugs c/o John W. Eaton +University of Wisconsin-Madison +Department of Chemical Engineering +1415 Engineering Drive +Madison, Wisconsin 53706 USA +@end example + +@node Bug Reporting, Sending Patches, Bug Lists, Trouble +@appendixsec How to Report Bugs +@cindex bugs, reporting + +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! + +Often people omit facts because they think they know what causes the +problem and they conclude that some details don't matter. Thus, you might +assume that the name of the variable you use in an example does not matter. +Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a +stray memory reference which happens to fetch from the location where that +name is stored in memory; perhaps, if the name were different, the contents +of that location would fool the interpreter into doing the right thing +despite the bug. Play it safe and give a specific, complete example. + +Keep in mind that the purpose of a bug report is to enable someone to +fix the bug if it is not known. Always write your bug reports on +the assumption that the bug is not known. + +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' This cannot help us fix a bug. It is better to send a complete +bug report to begin with. + +Try to make your bug report self-contained. If we have to ask you for +more information, it is best if you include all the previous information +in your response, as well as the information that was missing. + +To enable someone to investigate the bug, you should include all these +things: + +@itemize @bullet +@item +The version of Octave. You can get this by noting the version number +that is printed when Octave starts, or running it with the @samp{-v} +option. + +@item +A complete input file that will reproduce the bug. + +A single statement may not be enough of an example---the bug might +depend on other details that are missing from the single statement where +the error finally occurs. + +@item +The command arguments you gave Octave to execute that example +and observe the bug. To guarantee you won't omit something important, +list all the options. + +If we were to try to guess the arguments, we would probably guess wrong +and then we would not encounter the bug. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +The command-line arguments you gave to the @code{configure} command when +you installed the interpreter. + +@item +A complete list of any modifications you have made to the interpreter +source. + +Be precise about these changes---show a context diff for them. + +@item +Details of any other deviations from the standard procedure for installing +Octave. + +@cindex incorrect output +@cindex incorrect results +@cindex results, incorrect +@cindex answers, incorrect +@cindex erroneous results +@cindex wrong answers +@item +A description of what behavior you observe that you believe is +incorrect. For example, "The interpreter gets a fatal signal," or, "The +output produced at line 208 is incorrect." + +Of course, if the bug is that the interpreter gets a fatal signal, then +one can't miss it. But if the bug is incorrect output, we might not +notice unless it is glaringly wrong. + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of the interpreter is out of synch, or you have encountered a bug +in the C library on your system. Your copy might crash and the copy +here would not. If you said to expect a crash, then when the +interpreter here fails to crash, we would know that the bug was not +happening. If you don't say to expect a crash, then we would not know +whether the bug was happening. We would not be able to draw any +conclusion from our observations. + +Often the observed symptom is incorrect output when your program is run. +Unfortunately, this is not enough information unless the program is +short and simple. It is very helpful if you can include an explanation +of the expected output, and why the actual output is incorrect. + +@item +If you wish to suggest changes to the Octave source, send them as +context diffs. If you even discuss something in the Octave source, +refer to it by context, not by line number, because the line numbers in +the development sources probalby won't match those in your sources. +@end itemize + +Here are some things that are not necessary: + +@itemize @bullet +@cindex bugs, investigating +@item +A description of the envelope of the bug. + +Often people who encounter a bug spend a lot of time investigating which +changes to the input file will make the bug go away and which changes +will not affect it. Such information is usually not necessary to enable +us to fix bugs in Octave, but if you can find a simpler example to +report @emph{instead} of the original one, that is a convenience. +Errors in the output will be easier to spot, running under the debugger +will take less time, etc. Most Octave bugs involve just one function, so +the most straightforward way to simplify an example is to delete all the +function definitions except the one in which the bug occurs. + +However, simplification is not vital; if you don't want to do +this, report the bug anyway and send the entire test case you +used. + +@item +A patch for the bug. Patches can be helpful, but if you find a bug, you +should report it, even if you cannot send a fix for the problem. +@end itemize + +@node Sending Patches, Service, Bug Reporting, Trouble +@appendixsec Sending Patches for Octave +@cindex improving Octave +@cindex diffs, submitting +@cindex patches, submitting +@cindex submitting diffs +@cindex submitting patches + +If you would like to write bug fixes or improvements for Octave, that is +very helpful. When you send your changes, please follow these +guidelines to avoid causing extra work for us in studying the patches. + +If you don't follow these guidelines, your information might still be +useful, but using it will take extra work. Maintaining Octave is a lot +of work in the best of circumstances, and we can't keep up unless you do +your best to help. + +@itemize @bullet +@item +Send an explanation with your changes of what problem they fix or what +improvement they bring about. For a bug fix, just include a copy of the +bug report, and explain why the change fixes the bug. + +@item +Always include a proper bug report for the problem you think you have +fixed. We need to convince ourselves that the change is right before +installing it. Even if it is right, we might have trouble judging it if +we don't have a way to reproduce the problem. + +@item +Include all the comments that are appropriate to help people reading the +source in the future understand why this change was needed. + +@item +Don't mix together changes made for different reasons. +Send them @emph{individually}. + +If you make two changes for separate reasons, then we might not want to +install them both. We might want to install just one. + +@item +Use @samp{diff -c} to make your diffs. Diffs without context are hard +for us to install reliably. More than that, they make it hard for us to +study the diffs to decide whether we want to install them. Unidiff +format is better than contextless diffs, but not as easy to read as +@samp{-c} format. + +If you have GNU diff, use @samp{diff -cp}, which shows the name of the +function that each change occurs in. + +@item +Write the change log entries for your changes. + +Read the @file{ChangeLog} file to see what sorts of information to put +in, and to learn the style that we use. The purpose of the change log +is to show people where to find what was changed. So you need to be +specific about what functions you changed; in large functions, it's +often helpful to indicate where within the function the change was made. + +On the other hand, once you have shown people where to find the change, +you need not explain its purpose. Thus, if you add a new function, all +you need to say about it is that it is new. If you feel that the +purpose needs explaining, it probably does---but the explanation will be +much more useful if you put it in comments in the code. + +If you would like your name to appear in the header line for who made +the change, send us the header line. +@end itemize + +@node Service, , Sending Patches, Trouble +@appendixsec How To Get Help with Octave +@cindex help, where to find + +If you need help installing, using or changing Octave, the mailing list + +@example +help-octave@@bevo.che.wisc.edu +@end example + +exists for the discussion of Octave matters related to using, +installing, and porting Octave. If you would like to join the +discussion, please send a short note to + +@example +help-octave-request@@bevo.che.wisc.edu + ^^^^^^^ +@end example + +@strong{Please do not} send requests to be added or removed from the the +mailing list, or other administrative trivia to the list itself.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/bugs1.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,23 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@setfilename BUGS +@set BUGSONLY + +@include conf.texi + +@c The immediately following lines apply to the BUGS file +@c which is generated using this file. + +This file documents known bugs in Octave and describes where and how to +report any bugs that you may find. + +Copyright (C) 1996 John W. Eaton. You may copy, distribute, and +modify it freely as long as you preserve this copyright notice and +permission notice. + +@node Trouble,,, (dir) +@chapter Known Causes of Trouble with Octave +@include bugs.texi +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/control.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,471 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Control Theory, Signal Processing, Quadrature, Top +@chapter Control Theory + +@ftable @code +@item abcddim (@var{a}, @var{b}, @var{c}, @var{d}) + +Check for compatibility of the dimensions of the matrices defining +the linear system [A, B, C, D] corresponding to +@iftex +@tex +$$ + {dx\over dt} = A x + B u +$$ +$$ + y = C x + D u +$$ +@end tex +@end iftex +@ifinfo + +@example +dx/dt = a x + b u +y = c x + d u +@end example + +@end ifinfo +or a similar discrete-time system. + +If the matrices are compatibly dimensioned, then @code{abcddim} returns +@var{n} = number of system states, @var{m} = number of system inputs, +and @var{p} = number of system outputs. Otherwise @code{abcddim} +returns @var{n} = @var{m} = @var{p} = @minus{}1. + +@item are (@var{a}, @var{b}, @var{c}, @var{opt}) + +Returns the solution, @var{x}, of the algebraic Riccati equation + +@example +a' x + x a - x b x + c = 0 +@end example + +@noindent +for identically dimensioned square matrices @var{a}, @var{b}, @var{c}. +If @var{b} (@var{c}) is not square, then the function attempts to use +@code{@var{b}*@var{b}'} (@code{@var{c}'*@var{c}}) instead. + +Solution method: apply Laub's Schur method (IEEE Transactions on +Automatic Control, 1979) to the appropriate Hamiltonian matrix. + +@var{opt} is an option passed to the eigenvalue balancing routine. +Default is @code{"B"}. + +@item c2d (@var{a}, @var{b}, @var{t}) +Converts the continuous time system described by: +@iftex +@tex +$$ + {dx\over dt} = A x + B u +$$ +@end tex +@end iftex +@ifinfo + +@example +dx/dt = a x + b u +@end example + +@end ifinfo +into a discrete time equivalent model +@iftex +@tex +$$ + x_{k+1} = A_d x_k + B_d u_k +$$ +@end tex +@end iftex +@ifinfo + +@example +x[k+1] = Ad x[k] + Bd u[k] +@end example +@end ifinfo + +@noindent +via the matrix exponential assuming a zero-order hold on the input and +sample time @var{t}. + +@item dare (@var{a}, @var{b}, @var{c}, @var{r}, @var{opt}) + +Returns the solution, @var{x} of the discrete-time algebraic Riccati +equation + +@example +a' x a - x + a' x b (r + b' x b)^(-1) b' x a + c = 0 +@end example + +@noindent +for matrices with dimensions: + +@example +@var{a}: @var{n} by @var{n} +@var{b}: @var{n} by @var{m} +@var{c}: @var{n} by @var{n}, symmetric positive semidefinite +@var{r}: @var{m} by @var{m}, symmetric positive definite (invertible) +@end example + +If @var{c} is not square, then the function attempts to use +@code{@var{c}'*@var{c}} instead. + +Solution method: Laub's Schur method (IEEE Transactions on Automatic +Control, 1979) is applied to the appropriate symplectic matrix. + +See also: Ran and Rodman, @cite{Stable Hermitian Solutions of Discrete +Algebraic Riccati Equations}, Mathematics of Control, Signals and +Systems, Volume 5, Number 2 (1992). + +@var{opt} is an option passed to the eigenvalue balancing routine. +The default is @code{"B"}. + +@item dgram (@var{a}, @var{b}) +Returns the discrete controllability and observability gramian for the +discrete time system described by +@iftex +@tex +$$ + x_{k+1} = A x_k + B u_k +$$ +$$ + y_k = C x_k + D u_k +$$ +@end tex +@end iftex +@ifinfo + +@example +x[k+1] = A x[k] + B u[k] + y[k] = C x[k] + D u[k] +@end example +@end ifinfo + +@code{dgram (@var{a}, @var{b})} returns the discrete controllability +gramian and @code{dgram (@var{a}', @var{c}')} returns the observability +gramian. + +@item dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv} [, @var{z}]) +Linear quadratic estimator (Kalman filter) design for the discrete time +system +@iftex +@tex +$$ + x_{k+1} = A x_k + B u_k + G w_k +$$ +$$ + y_k = C x_k + D u_k + w_k +$$ +@end tex +@end iftex +@ifinfo + +@example +x[k+1] = A x[k] + B u[k] + G w[k] + y[k] = C x[k] + D u[k] + w[k] +@end example + +@end ifinfo +where @var{w}, @var{v} are zero-mean gaussian noise processes with +respective intensities @code{@var{sigw} = cov (@var{w}, @var{w})} and +@code{@var{sigv} = cov (@var{v}, @var{v})}. + +If specified, @var{z} is @code{cov (@var{w}, @var{v})}. Otherwise +@code{cov (@var{w}, @var{v}) = 0}. + +The observer structure is +@iftex +@tex +$$ + z_{k+1} = A z_k + B u_k + k(y_k - C z_k - D u_k) +$$ +@end tex +@end iftex +@ifinfo + +@example +z[k+1] = A z[k] + B u[k] + k(y[k] - C z[k] - D u[k]) +@end example +@end ifinfo + +@noindent +Returns: + +@var{l} is the observer gain, @code{(A - A L C)} is stable. + +@var{m} is the Ricatti equation solution. + +@var{p} is the estimate error covariance after the measurement update. + +@var{e} are the closed loop poles of @code{(A - A L C)}. + + +@item dlqr (@var{a}, @var{b}, @var{q}, @var{r} [, @var{z}]) +Linear quadratic regulator design for the discrete time system +@iftex +@tex +$$ + x_{k+1} = A x_k + B u_k +$$ +@end tex +@end iftex +@ifinfo + +@example +x[k+1] = A x[k] + B u[k] +@end example + +@end ifinfo +to minimize the cost functional + +@example +J = Sum [ x' Q x + u' R u ], Z omitted +@end example + +@noindent +or + +@example +J = Sum [ x' Q x + u' R u +2 x' Z u ], Z included +@end example + +@noindent +Returns: + +@var{k} is the state feedback gain, @code{(A - B K)} is stable. + +@var{p} is the solution of algebraic Riccati equation. + +@var{e} are the closed loop poles of @var{(A - B K)}. + +@item dlyap (@var{a}, @var{b}) +Solve the discrete-time Lyapunov equation + +@example +a x a' - x + b = 0 +@end example + +@noindent +for square matrices @var{a}, @var{b}. If @var{b} is not square, then the +function attempts to solve either + +@example +a x a' - x + b b' = 0 +@end example + +@noindent +or + +@example +a' x a - x + b' b = 0 +@end example + +@noindent +whichever is appropriate. + +Uses Schur decomposition method as in Kitagawa, International Journal of +Control (1977); column-by-column solution method as suggested in +Hammarling, IMA Journal of Numerical Analysis, (1982). + +@item is_controllable (@var{a}, @var{b}, @var{tol}) + +If the pair (a, b) is controllable, then return value 1. +Otherwise, returns a value of 0. + +@var{tol} is a roundoff parameter, set to @code{2*eps} if omitted. + +Currently just constructs the controllability matrix and checks rank. +A better method is as follows (Boley and Golub, Systems and Control +Letters, 1984): Controllability is determined by applying Arnoldi +iteration with complete re-orthogonalization to obtain an orthogonal +basis of the Krylov subspace +@iftex +@tex +$$ + {\rm span} \left(\left[b~ab~\ldots~a^{n-1}b\right]\right) +$$ +@end tex +@end iftex +@ifinfo + +@example + n-1 + span ([b, a*b, ..., a^ *b]). +@end example +@end ifinfo + +@item is_observable (@var{a}, @var{c}, @var{tol}) + +Returns 1 if the pair @code{(a, c)} is observable. +Otherwise, returns a value of 0. + +@item lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) + +@example +[k, p, e] = lqe (a, g, c, sigw, sigv, z) +@end example + +Linear quadratic estimator (Kalman filter) design for the continuous +time system +@iftex +@tex +$$ + {dx\over dt} = A x + B u +$$ +$$ + y = C x + D u +$$ +@end tex +@end iftex +@ifinfo + +@example +dx +-- = a x + b u +dt + +y = c x + d u +@end example + +@end ifinfo +where @var{w}, @var{v} are zero-mean gaussian noise processes with +respective intensities + +@example +sigw = cov (w, w) +sigv = cov (v, v) +@end example + +@noindent +@var{z} (if specified) is the cross-covariance +@code{cov (@var{w}, @var{v})}; the default value is +@code{cov (@var{w}, @var{v}) = 0}. + +Observer structure is @code{dz/dt = A z + B u + k (y - C z - D u)} + +returns: + +@var{k} is observer gain: @code{(A - K C)} is stable. + +@var{p} is solution of algebraic Riccati equation. + +@var{e} is the vector of closed loop poles of @code{(A - K C)}. + +@item lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +@itemx [@var{k}, @var{p}, @var{e}] = lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +Linear quadratic regulator design for the continuous time system +@iftex +@tex +$$ + {dx\over dt} = A x + B u +$$ +@end tex +@end iftex +@ifinfo + +@example +dx +-- = A x + B u +dt +@end example + +@end ifinfo +to minimize the cost functional +@iftex +@tex +$$ + J = \int_0^\infty x' Q x + u' R u +$$ +@end tex +@end iftex +@ifinfo + +@example + infinity + / + J = | x' Q x + u' R u + / + t=0 +@end example +@end ifinfo + +@noindent +@var{z} omitted or +@iftex +@tex +$$ + J = \int_0^\infty x' Q x + u' R u + 2 x' Z u +$$ +@end tex +@end iftex +@ifinfo + +@example + infinity + / + J = | x' Q x + u' R u + 2 x' Z u + / + t=0 +@end example + +@end ifinfo +@var{z} included + +@noindent +Returns: + +@var{k} is state feedback gain: @code{(A - B K)} is stable. + +@var{p} is the stabilizing solution of appropriate algebraic Riccati +equation. + +@var{e} is the vector of the closed loop poles of @code{(A - B K)}. + +@item lyap (@var{a}, @var{b}, @var{c}) + +Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart +algorithm (Communications of the ACM, 1972). + +If @code{(a, b, c)} are specified, then @code{lyap} returns the solution +of the Sylvester equation + +@example +a x + x b + c = 0 +@end example + +If only @code{(a, b)} are specified, then @code{lyap} returns the +solution of the Lyapunov equation + +@example +a' x + x a + b = 0 +@end example + +If @var{b} is not square, then @code{lyap} returns the solution of either + +@example +a' x + x a + b' b = 0 +@end example + +@noindent +or + +@example +a x + x a' + b b' = 0 +@end example + +@noindent +whichever is appropriate. + +Solves by using the Bartels-Stewart algorithm (1972). + +@item tzero (@var{a}, @var{b}, @var{c}, @var{d}, @var{bal}) + +Compute the transmission zeros of [A, B, C, D]. + +@var{bal} = balancing option (see balance); default is @code{"B"}. + +Needs to incorporate @code{mvzero} algorithm to isolate finite zeros; +see Hodel, @cite{Computation of System Zeros with Balancing}, Linear +Algebra and its Applications, July 1993. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/cp-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,8 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Concept Index, Variable Index, Using Info, Top +@unnumbered Concept Index + +@printindex cp
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/diffeq.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,167 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Differential Equations, Optimization, Nonlinear Equations, Top +@chapter Differential Equations + +Octave has two built-in functions for solving differential equations. +Both are based on reliable ODE solvers written in Fortran. + +@menu +* Ordinary Differential Equations:: +* Differential-Algebraic Equations:: +@end menu + +@cindex Differential Equations +@cindex ODE +@cindex DAE + +@node Ordinary Differential Equations, Differential-Algebraic Equations, Differential Equations, Differential Equations +@section Ordinary Differential Equations + +@findex lsode +The function @code{lsode} can be used Solve ODEs of the form +@iftex +@tex +$$ + {dx\over dt} = f (x, t) +$$ +@end tex +@end iftex +@ifinfo + +@example +dx +-- = f (x, t) +dt +@end example +@end ifinfo + +@noindent +using Hindmarsh's ODE solver LSODE. + +@example +lsode (@var{fcn}, @var{x0}, @var{t_out}, @var{t_crit}) +@end example + +The first argument is the name of the function to call to +compute the vector of right hand sides. It must have the form + +@example +@var{xdot} = f (@var{x}, @var{t}) +@end example + +@noindent +where @var{xdot} and @var{x} are vectors and @var{t} is a scalar. + +The second argument specifies the initial condition, and the third +specifies a vector of output times at which the solution is desired, +including the time corresponding to the initial condition. + +The fourth argument is optional, and may be used to specify a set of +times that the ODE solver should not integrate past. It is useful for +avoiding difficulties with singularities and points where there is a +discontinuity in the derivative. + +@findex lsode_options +Tolerances and other options for @code{lsode} may be specified using the +function @code{lsode_options}. + +Here is an example of solving a set of two differential equations using +@code{lsode}. The function + +@example +function xdot = f (x, t) + + r = 0.25; + k = 1.4; + a = 1.5; + b = 0.16; + c = 0.9; + d = 0.8; + + xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1)); + xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); + +endfunction +@end example + +@noindent +is integrated with the command + +@example +x = lsode ("f", [1; 2], (t = linspace (0, 50, 200)')); +@end example + +@noindent +producing a set of 200 values stored in the variable @var{x}. Note that +this example takes advantage of the fact that an assignment produces a +value to store the values of the output times in the variable @var{t} +directly in the function call The results can then be plotted using +the command + +@example +plot (t, x) +@end example + +See Alan C. Hindmarsh, @cite{ODEPACK, A Systematized Collection of ODE +Solvers}, in Scientific Computing, R. S. Stepleman, editor, (1983) for +more information about this family of ODE solvers. + +@node Differential-Algebraic Equations, , Ordinary Differential Equations, Differential Equations +@section Differential-Algebraic Equations + +@findex dassl +The function @code{dassl} can be used Solve DAEs of the form +@iftex +@tex +$$ + 0 = f (\dot{x}, x, t), \qquad x(t=0) = x_0, \dot{x}(t=0) = \dot{x}_0 +$$ +@end tex +@end iftex +@ifinfo + +@example +0 = f (x-dot, x, t), x(t=0) = x_0, x-dot(t=0) = x-dot_0 +@end example +@end ifinfo + +@example +dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t_out}, @var{t_crit}) +@end example + +The first argument is the name of the function to call to +compute the vector of residuals. It must have the form + +@example +@var{res} = f (@var{x}, @var{xdot}, @var{t}) +@end example + +@noindent +where @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a +scalar. + +The second and third arguments to @code{dassl} specify the initial +condition of the states and their derivatives, and the fourth argument +specifies a vector of output times at which the solution is desired, +including the time corresponding to the initial condition. + +The set of initial states and derivatives are not strictly required to +be consistent. In practice, however, DASSL is not very good at +determining a consistent set for you, so it is best if you ensure that +the initial values result in the function evaluating to zero. + +The fifth argument is optional, and may be used to specify a set of +times that the DAE solver should not integrate past. It is useful for +avoiding difficulties with singularities and points where there is a +discontinuity in the derivative. + +@findex dassl_options +Tolerances and other options for @code{dassl} may be specified using the +function @code{dassl_options}. + +See K. E. Brenan, et al., @cite{Numerical Solution of Initial-Value +Problems in Differential-Algebraic Equations}, North-Holland (1989) for +more information about the implementation of DASSL.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/dir Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,13 @@ +-*- Text -*- +This is the file .../info/dir, which contains the topmost node of the +Info hierarchy. The first time you invoke Info you start off +looking at that node, which is (dir)Top. + +File: dir Node: Top This is the top of the INFO tree + This (the Directory node) gives a menu of major topics. + Typing "d" returns here, "q" exits, "?" lists all INFO commands, "h" + gives a primer for first-timers, "mItem<Return>" visits the menu + item named `Item', etc. + +* Octave: (octave). + Interactive language for numerical computations.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/emacs.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,489 @@ +@c Copyright (C) 1996 John W. Eaton +@c Written by Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at> on 1996/05/17 +@c Updated for octave.el version 0.8.3 by KH on 1996/07/02 +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Emacs +@chapter Using Emacs With Octave + +The development of Octave code can greatly be facilitated using Emacs +with Octave mode, a major mode for editing Octave files which can e.g.@: +automatically indent the code, do some of the typing (with Abbrev mode) +and show keywords, comments, strings, etc.@: in different faces (with +Font-lock mode on devices that support it). + +It is also possible to run Octave from within Emacs, either by directly +entering commands at the prompt in a buffer in Inferior Octave mode, or +by interacting with Octave from within a file with Octave code. This is +useful in particular for debugging Octave code. + +Finally, you can convince Octave to use the Emacs info reader for +@kbd{help -i}. + +All functionality is provided by the Emacs Lisp package @file{octave}. +This chapter describes how to set up and use this package. + +Please contact <Kurt.Hornik@@ci.tuwien.ac.at> if you have any questions +or suggestions on using Emacs with Octave. + +@menu +* Setting Up Octave Mode:: +* Using Octave Mode:: +* Running Octave From Within Emacs:: +* Using the Emacs Info Reader for Octave:: +@end menu + +@node Setting Up Octave Mode, Using Octave Mode, Emacs, Emacs +@section Setting Up Octave Mode + +If you are lucky, your sysadmins have already arranged everything so +that Emacs automatically goes into Octave mode whenever you visit an +Octave code file as characterized by its extension @file{.m}. If not, +proceed as follows. + +@enumerate +@item +Make sure that the file @file{octave.el} (or even better, its +byte-compiled version @file{octave.elc}) from the Octave distribution is +somewhere in your load-path. + +@quotation +@strong{Note:} The current version of @file{octave.el} was developed, +tested and byte-compiled under GNU Emacs 19.31. It may not work under +other Emacs versions, in particular under XEmacs. +@end quotation + +@item +To begin using Octave mode for all @file{.m} files you visit, add the +following lines to a file loaded by Emacs at startup time, typically +your @file{~/.emacs} file: + +@lisp +(autoload 'octave-mode "octave" nil t) +(setq auto-mode-alist + (cons '(\"\\\\.m$\" . octave-mode) auto-mode-alist)) +@end lisp + +@item +Finally, to turn on the abbrevs, auto-fill and font-lock features +automatically, also add the following lines to one of the Emacs startup +files: +@lisp +(add-hook 'octave-mode-hook + (lambda () + (abbrev-mode 1) + (auto-fill-mode 1) + (if (eq window-system 'x) + (font-lock-mode 1)))) +@end lisp +See the Emacs manual for more information about how to customize +Font-lock mode. +@end enumerate + +@node Using Octave Mode, Running Octave From Within Emacs, Setting Up Octave Mode, Emacs +@section Using Octave Mode + +In Octave mode, the following special Emacs commands can be used in +addition to the standard Emacs commands. + +@table @kbd +@item C-h m +Describe the features of Octave mode. + +@item LFD +Reindent the current Octave line, insert a newline and indent the new +line (@code{octave-reindent-then-newline-and-indent}). An abbrev before +point is expanded if @code{abbrev-mode} is non-@code{nil}. + +@item TAB +Indents current Octave line based on its contents and on previous +lines (@code{indent-according-to-mode}). + +@item ; +Insert an ``electric'' semicolon (@code{octave-electric-semi}). If +@code{octave-auto-indent} is non-@code{nil}, typing a @samp{;} +automatically reindents the current line, inserts a newline and indents +the new line. + +@item ` +Start entering an abbreviation (@code{octave-abbrev-start}). If Abbrev +mode is turned on, typing @kbd{`C-h} or @kbd{`?} lists all abbrevs. +Any other key combination is executed normally. + +@item M-LFD +Break line at point and insert continuation marker and alignment +(@code{octave-split-line}). + +@item M-TAB +Perform completion on Octave symbol preceding point, comparing that +symbol against Octave's reserved words and builtin variables +(@code{octave-complete-symbol}). + +@item M-C-a +Move backward to the beginning of a function +(@code{octave-beginning-of-defun}). +With prefix argument @var{N}, do it that many times if @var{N} is +positive; otherwise, move forward to the @var{N}-th following beginning +of a function. + +@item M-C-e +Move forward to the end of a function (@code{octave-end-of-defun}). +With prefix argument @var{N}, do it that many times if @var{N} is +positive; otherwise, move back to the @var{N}-th preceding end of a +function. + +@item M-C-h +Puts point at beginning and mark at the end of the current Octave +function, i.e., the one containing point or following point +(@code{octave-mark-defun}). + +@item M-C-q +Properly indents the Octave function which contains point +(@code{octave-indent-defun}). + +@item C-c ; +Puts the first character of @code{octave-comment-start} (usually +@samp{#}) at the beginning of every line in the region +(@code{octave-comment-region}). With just @kbd{C-u} prefix argument, +uncomment each line in the region. + +@item C-c : +Uncomments every line in the region (@code{octave-uncomment-region}). + +@item C-c C-p +Move one line of Octave code backward, skipping empty and comment lines +(@code{octave-previous-code-line}). With numeric prefix argument +@var{N}, move that many code lines backward (forward if @var{N} is +negative). + +@item C-c C-n +Move one line of Octave code forward, skipping empty and comment lines +(@code{octave-next-code-line}). With numeric prefix argument @var{N}, +move that many code lines forward (backward if @var{N} is negative). + +@item C-c C-a +Move to the `real' beginning of the current line +(@code{octave-beginning-of-line}). If point is in an empty or comment +line, simply go to its beginning; otherwise, move backwards to the +beginning of the first code line which is not inside a continuation +statement, i.e., which does not follow a code line ending in @samp{...} +or @samp{\}, or is inside an open parenthesis list. + +@item C-c C-e +Move to the `real' end of the current line (@code{octave-end-of-line}). +If point is in a code line, move forward to the end of the first Octave +code line which does not end in @samp{...} or @samp{\} or is inside an +open parenthesis list. Otherwise, simply go to the end of the current +line. + +@item C-c M-C-n +Move forward across one balanced begin-end block of Octave code +(@code{octave-forward-block}). With numeric prefix argument @var{N}, +move forward across @var{n} such blocks (backward if @var{N} is +negative). + +@item C-c M-C-p +Move back across one balanced begin-end block of Octave code +(@code{octave-backward-block}). With numeric prefix argument @var{N}, +move backward across @var{N} such blocks (forward if @var{N} is +negative). + +@item C-c M-C-d +Move forward down one begin-end block level of Octave code +(@code{octave-down-block}). With numeric prefix argument, do it that +many times; a negative argument means move backward, but still go down +one level. + +@item C-c M-C-u +Move backward out of one begin-end block level of Octave code +(@code{octave-backward-up-block}). With numeric prefix argument, do it +that many times; a negative argument means move forward, but still to a +less deep spot. + +@item C-c M-C-h +Put point at the beginning of this block, mark at the end +(@code{octave-mark-block}). +The block marked is the one that contains point or follows point. + +@item C-c ] +Close the current block on a separate line (@code{octave-close-block}). +An error is signaled if no block to close is found. + +@item C-c f +Insert a function skeleton, prompting for the function's name, arguments +and return values which have to be entered without parens +(@code{octave-insert-defun}). + +@item C-c C-h +Search the function, operator and variable indices of all info files +with documentation for Octave for entries (@code{octave-help}). If used +interactively, the entry is prompted for with completion. If multiple +matches are found, one can cycle through them using the standard +@samp{,} (@code{Info-index-next}) command of the Info reader. + +The variable @code{octave-help-files} is a list of files to search +through and defaults to @code{'("octave")}. If there is also an Octave +Local Guide with corresponding info file @file{octave-LG} (for example), +you can have @code{octave-help} search both files by +@lisp +(setq octave-help-files '("octave" "octave-LG")) +@end lisp +@noindent +in one of your Emacs startup files. + +@end table + +A common problem is that the @key{RET} key does @emph{not} indent the +line to where the new text should go after inserting the newline. This +is because the standard Emacs convention is that @key{RET} (aka +@kbd{C-m}) just adds a newline, whereas @key{LFD} (aka @kbd{C-j}) adds a +newline and indents it. This is particularly inconvenient for users with +keyboards which do not have a special @key{LFD} key at all; in such +cases, it is typically more convenient to use @key{RET} as the @key{LFD} +key (rather than typing @kbd{C-j}). + +You can make @key{RET} do this by adding +@lisp +(define-key octave-mode-map "\C-m" + 'octave-reindent-then-newline-and-indent) +@end lisp +@noindent +to one of your Emacs startup files. Another, more generally applicable +solution is +@lisp +(defun RET-behaves-as-LFD () + (let ((x (key-binding "\C-j"))) + (local-set-key "\C-m" x))) +(add-hook 'octave-mode-hook 'return-behaves-as-LFD) +@end lisp +@noindent +(this works for all modes by adding to the startup hooks, without having +to know the particular binding of @key{RET} in that mode!). Similar +considerations apply for using @key{M-RET} as @key{M-LFD}. As Barry +A. Warsaw <bwarsaw@@cnri.reston.va.us> says in the documentation for his +@code{cc-mode}, ``This is a very common question. @code{:-)} If you want +this to be the default behavior, don't lobby me, lobby RMS!'' + +The following variables can be used to customize Octave mode. + +@table @code +@item octave-auto-newline +Non-@code{nil} means auto-insert a newline and indent after semicolons +are typed. The default value is @code{nil}. + +@item octave-blink-matching-block +Non-@code{nil} means show matching begin of block when inserting a space, +newline or @samp{;} after an else or end keyword. Default is @code{t}. +This is an extremely useful feature for automatically verifying that the +keywords match---if they don't, an error message is displayed. + +@item octave-block-offset +Extra indentation applied to statements in block structures. +Default is 2. + +@item octave-comment-column +Column to indent right-margin comments to. +Default is 32. +(Such comments are created using @key{M-;} (@code{indent-for-comment}).) + +@item octave-comment-start +Delimiter inserted to start new comment. +Default value is @samp{# }. + +@item octave-continuation-offset +Extra indentation applied to Octave continuation lines. +Default is 4. + +@item octave-continuation-string +String used for Octave continuation lines. +Normally @samp{\}. + +@item octave-fill-column +Column beyond which automatic line-wrapping should happen. +Default is 72. + +@item octave-inhibit-startup-message +If @code{t}, no startup message is displayed when Octave mode is +called. +Default is @code{nil}. + +@end table + +If Font Lock mode is enabled, Octave mode will display +@itemize @bullet +@item +strings in @code{font-lock-string-face} +@item +comments in @code{font-lock-comment-face} +@item +the Octave reserved words (such as all block keywords) and the text +functions (such as @samp{cd} or @samp{who}) which are also reserved +using @code{font-lock-keyword-face} +@item +the builtin operators (@samp{&&}, @samp{<>}, @dots{}) using +@code{font-lock-reference-face} +@item +the builtin variables (such as @samp{prefer_column_vectors}, @samp{NaN} +or @samp{LOADPATH}) in @code{font-lock-variable-name-face} +@item +and the function names in function declarations in +@code{font-lock-function-name-face}. +@end itemize + +There is also rudimentary support for Imenu (currently, function names +can be indexed). + +Customization of Octave mode can be performed by modification of the +variable @code{octave-mode-hook}. It the value of this variable is +non-@code{nil}, turning on Octave mode calls its value. + +If you discover a problem with Octave mode, you can conveniently send a +bug report using @kbd{C-c C-b} (@code{octave-submit-bug-report}). This +automatically sets up a mail buffer with version information already +added. You just need to add a description of the problem, including a +reproducible test case and send the message. + +@node Running Octave From Within Emacs, Using the Emacs Info Reader for Octave, Using Octave Mode, Emacs +@section Running Octave From Within Emacs + +The package @file{octave} provides commands for running an inferior +Octave process in a special Emacs buffer. Use +@lisp +M-x run-octave +@end lisp +@noindent +to directly start an inferior Octave process. If Emacs does not know +about this command, add the line +@lisp +(autoload 'run-octave "octave" nil t) +@end lisp +@noindent +to your @file{.emacs} file. + +This will start Octave in a special buffer the name of which is +specified by the variable @code{inferior-octave-buffer} and defaults to +@code{"*Octave Interaction*"}. From within this buffer, you can +interact with the inferior Octave process `as usual', i.e., by entering +Octave commands at the prompt. + +You can also communicate with an inferior Octave process from within +files with Octave code (i.e., buffers in Octave mode), using the +following commands. + +@table @kbd +@item C-c i l +Send the current line to the inferior Octave process +(@code{octave-send-line}). +With positive prefix argument @var{N}, send that many lines. +If @code{octave-send-line-auto-forward} is non-@code{nil}, go to the +next unsent code line. +@item C-c i b +Send the current block to the inferior Octave process +(@code{octave-send-block}). +@item C-c i f +Send the current function to the inferior Octave process +(@code{octave-send-defun}). +@item C-c i r +Send the region to the inferior Octave process +(@code{octave-send-region}). +@item C-c i s +Make sure that `inferior-octave-buffer' is displayed +(@code{octave-show-process-buffer}). +@item C-c i h +Delete all windows that display @file{inferior-octave-buffer} +(@code{octave-hide-process-buffer}). +@item C-c i k +Kill the inferior Octave process and its buffer +(@code{octave-kill-process}). +@end table + +The effect of the commands which send code to the Octave process can be +customized by the following variables. +@table @code +@item octave-send-echo-input +Non-@code{nil} means echo input sent to the inferior Octave process. +Default is @code{t}. + +@item octave-send-show-buffer +Non-@code{nil} means display the buffer running the Octave process after +sending a command (but without selecting it). +Default is @code{t}. +@end table + +If you send code and there is no inferior Octave process yet, it will be +started automatically. + +The startup of the inferior Octave process is highly customizable. +The variable @code{inferior-octave-startup-args} can be used for +specifying command lines arguments to be passed to Octave on startup +as a list of strings. For example, to suppress the startup message and +use `traditional' mode, set this to @code{'("-q" "--traditional")}. +You can also specify a startup file of Octave commands to be loaded on +startup; note that these commands will not produce any visible output +in the process buffer. Which file to use is controlled by the variable +@code{inferior-octave-startup-file}. If this is @code{nil}, the file +@file{~/.emacs_octave} is used if it exists. + +And finally, @code{inferior-octave-mode-hook} is run after starting the +process and putting its buffer into Inferior Octave mode. Hence, if you +like the up and down arrow keys to behave in the interaction buffer as +in the shell, and you want this buffer to use nice colors, add +@lisp +(add-hook 'inferior-octave-mode-hook + (lambda () + (turn-on-font-lock) + (define-key inferior-octave-mode-map [up] + 'comint-previous-input) + (define-key inferior-octave-mode-map [down] + 'comint-next-input))) +@end lisp +@noindent +to your @file{.emacs} file. You could also swap the roles of @kbd{C-a} +(@code{beginning-of-line}) and @code{C-c C-a} (@code{comint-bol}) using +this hook. + +@quotation +@strong{Note:} +If you set your Octave prompts to something different from the defaults, +make sure that @code{inferior-octave-prompt} matches them. +Otherwise, @emph{nothing} will work, because Emacs will have no idea +when Octave is waiting for input, or done sending output. +@end quotation + +@node Using the Emacs Info Reader for Octave, , Running Octave From Within Emacs, Emacs +@section Using the Emacs Info Reader for Octave + +You can also set up the Emacs Info reader for dealing with the results +of Octave's @samp{help -i}. For this, the package @file{gnuserv} needs +to be installed, which unfortunately still does not come with GNU Emacs +(it does with XEmacs). It can be retrieved from any GNU Emacs Lisp Code +Directory archive, e.g.@: +@file{ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive}, +in the @file{packages} subdirectory. There is also a newer version +around (use archie to look for @file{gnuserv-2.1alpha.tar.gz}). + +If @file{gnuserv} is installed, add the lines +@lisp +(autoload 'octave-help "octave" nil t) +(require 'gnuserv) +(gnuserv-start) +@end lisp +@noindent +to your @file{.emacs} file. + +You can use either `plain' Emacs Info or the function @code{octave-help} +as your Octave info reader (for @samp{help -i}). In the former case, +set the Octave variable @code{INFO_PROGRAM} to @code{"info-emacs-info"}. +The latter is perhaps more attractive because it allows to look up keys +in the indices of @emph{several} info files related to Octave (provided +that the Emacs variable @code{octave-help-files} is set correctly). In +this case, set @code{INFO_PROGRAM} to @code{"info-emacs-octave-help"}. + +If you use Octave from within Emacs, these settings are best done in the +@file{~/.emacs_octave} startup file (or the file pointed to by the Emacs +variable @code{inferior-octave-startup-file}). + +@c Local Variables: +@c TeX-command-default: "Texinfo" +@c End:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/expr.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,1611 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Expressions, Statements, Invoking Octave, Top +@chapter Expressions +@cindex expressions + +Expressions are the basic building block of statements in Octave. An +expression evaluates to a value, which you can print, test, store in a +variable, pass to a function, or assign a new value to a variable with +an assignment operator. + +An expression can serve as a statement on its own. Most other kinds of +statements contain one or more expressions which specify data to be +operated on. As in other languages, expressions in Octave include +variables, array references, constants, and function calls, as well as +combinations of these with various operators. + +@menu +* Constant Expressions:: +* Matrices:: +* Ranges:: +* Variables:: +* Index Expressions:: +* Data Structures:: +* Calling Functions:: +* Global Variables:: +* Keywords:: +* Arithmetic Ops:: +* Comparison Ops:: +* Boolean Expressions:: +* Assignment Ops:: +* Increment Ops:: +* Operator Precedence:: +@end menu + +@node Constant Expressions, Matrices, Expressions, Expressions +@section Constant Expressions + +The simplest type of expression is the @dfn{constant}, which always has +the same value. There are two types of constants: numeric constants and +string constants. + +@menu +* Numeric Constants:: +* String Constants:: +@end menu + +@node Numeric Constants, String Constants, Constant Expressions, Constant Expressions +@subsection Numeric Constants +@cindex numeric constant +@cindex numeric value + +A @dfn{numeric constant} may be a scalar, a vector, or a matrix, and it +may contain complex values. + +The simplest form of a numeric constant, a scalar, is a single number +that can be an integer, a decimal fraction, a number in scientific +(exponential) notation, or a complex number. Note that all numeric +values are represented within Octave in double-precision floating point +format (complex constants are stored as pairs of double-precision +floating point values). Here are some examples of real-valued numeric +constants, which all have the same value: + +@example +105 +1.05e+2 +1050e-1 +@end example + +To specify complex constants, you can write an expression of the form + +@example +3 + 4i +3.0 + 4.0i +0.3e1 + 40e-1i +@end example + +all of which are equivalent. The letter @samp{i} in the previous example +stands for the pure imaginary constant, defined as +@iftex +@tex + $\sqrt{-1}$. +@end tex +@end iftex +@ifinfo + @code{sqrt (-1)}. +@end ifinfo + +For Octave to recognize a value as the imaginary part of a complex +constant, a space must not appear between the number and the @samp{i}. +If it does, Octave will print an error message, like this: + +@example +octave:13> 3 + 4 i + +parse error: + + 3 + 4 i + ^ +@end example + +You may also use @samp{j}, @samp{I}, or @samp{J} in place of the +@samp{i} above. All four forms are equivalent. + +@node String Constants, , Numeric Constants, Constant Expressions +@subsection String Constants +@cindex strings +@cindex character strings + +@opindex " +@opindex ' + +A @dfn{string constant} consists of a sequence of characters enclosed in +either double-quote or single-quote marks. For example, both of the +following expressions + +@example +"parrot" +'parrot' +@end example + +@noindent +represent the string whose contents are @samp{parrot}. Strings in +Octave can be of any length. + +Since the single-quote mark is also used for the transpose operator +(@pxref{Arithmetic Ops}) but double-quote marks have no other purpose in +Octave, it is best to use double-quote marks to denote strings. + +@c XXX FIXME XXX -- this is probably pretty confusing. + +@cindex escape sequence notation +Some characters cannot be included literally in a string constant. You +represent them instead with @dfn{escape sequences}, which are character +sequences beginning with a backslash (@samp{\}). + +One use of an escape sequence is to include a double-quote +(single-quote) character in a string constant that has been defined +using double-quote (single-quote) marks. Since a plain double-quote +would end the string, you must use @samp{\"} to represent a single +double-quote character as a part of the string. The backslash character +itself is another character that cannot be included normally. You must +write @samp{\\} to put one backslash in the string. Thus, the string +whose contents are the two characters @samp{"\} must be written +@code{"\"\\"}. + +Another use of backslash is to represent unprintable characters +such as newline. While there is nothing to stop you from writing most +of these characters directly in a string constant, they may look ugly. + +Here is a table of all the escape sequences used in Octave. They are +the same as those used in the C programming langauge. + +@table @code +@item \\ +Represents a literal backslash, @samp{\}. + +@item \" +Represents a literal double-quote character, @samp{"}. + +@item \' +Represents a literal single-quote character, @samp{'}. + +@item \a +Represents the ``alert'' character, control-g, ASCII code 7. + +@item \b +Represents a backspace, control-h, ASCII code 8. + +@item \f +Represents a formfeed, control-l, ASCII code 12. + +@item \n +Represents a newline, control-j, ASCII code 10. + +@item \r +Represents a carriage return, control-m, ASCII code 13. + +@item \t +Represents a horizontal tab, control-i, ASCII code 9. + +@item \v +Represents a vertical tab, control-k, ASCII code 11. + +@c We don't do octal or hex this way yet. +@c +@c @item \@var{nnn} +@c Represents the octal value @var{nnn}, where @var{nnn} are one to three +@c digits between 0 and 7. For example, the code for the ASCII ESC +@c (escape) character is @samp{\033}.@refill +@c +@c @item \x@var{hh}@dots{} +@c Represents the hexadecimal value @var{hh}, where @var{hh} are hexadecimal +@c digits (@samp{0} through @samp{9} and either @samp{A} through @samp{F} or +@c @samp{a} through @samp{f}). Like the same construct in @sc{ansi} C, +@c the escape +@c sequence continues until the first non-hexadecimal digit is seen. However, +@c using more than two hexadecimal digits produces undefined results. (The +@c @samp{\x} escape sequence is not allowed in @sc{posix} @code{awk}.)@refill +@end table + +Strings may be concatenated using the notation for defining matrices. +For example, the expression + +@example +[ "foo" , "bar" , "baz" ] +@end example + +@noindent +produces the string whose contents are @samp{foobarbaz}. The next +section explains more about how to create matrices. + +@node Matrices, Ranges, Constant Expressions, Expressions +@section Matrices +@cindex matrices + +@opindex [ +@opindex ] +@opindex ; +@opindex , + +It is easy to define a matrix of values in Octave. The size of the +matrix is determined automatically, so it is not necessary to explicitly +state the dimensions. The expression + +@example +a = [1, 2; 3, 4] +@end example + +@noindent +results in the matrix + +@example +a = + + 1 2 + 3 4 +@end example + +The commas which separate the elements on a row may be omitted, and the +semicolon that marks the beginning of a new row may be replaced by one +or more new lines. The expression + +@example +a = [ 1 2 + 3 4 ] +@end example + +@noindent +is equivalent to the one above. + +Elements of a matrix may be arbitrary expressions, provided that the +dimensions all agree. For example, given the above matrix, the +expression + +@example +[ a, a ] +@end example + +@noindent +produces the matrix + +@example +ans = + + 1 2 1 2 + 3 4 3 4 +@end example + +@noindent +but the expression + +@example +[ a 1 ] +@end example + +@noindent +produces the error + +@c XXX FIXME XXX -- this error should eventually have line and column +@c information associated with it. +@example +error: number of rows must match +@end example + +Inside the square brackets that delimit a matrix expression, Octave +looks at the surrounding context to determine whether spaces should be +converted into element separators, or simply ignored, so commands like + +@example +[ linspace (1, 2) ] +@end example + +@noindent +will work. However, some possible sources of confusion remain. For +example, in the expression + +@example +[ 1 - 1 ] +@end example + +@noindent +the @samp{-} is treated as a binary operator and the result is the +scalar 0, but in the expression + +@example +[ 1 -1 ] +@end example + +@noindent +the @samp{-} is treated as a unary operator and the result is the +vector @code{[ 1 -1 ]}. + +Given @code{a = 1}, the expression + +@example +[ 1 a' ] +@end example + +@noindent +results in the single quote character @samp{'} being treated as a +transpose operator and the result is the vector @code{[ 1 1 ]}, but the +expression + +@example +[ 1 a ' ] +@end example + +@noindent +produces the error message + +@example +error: unterminated string constant +@end example + +@noindent +because to not do so would make it impossible to correctly parse the +valid expression + +@example +[ a 'foo' ] +@end example + +For clarity, it is probably best to always use commas and semicolons to +separate matrix elements and rows. It is possible to enforce this style +by setting the built-in variable @code{whitespace_in_literal_matrix} to +@code{"ignore"}. @xref{Built-in Variables}. + +@menu +* Empty Matrices:: +@end menu + +@node Empty Matrices, , Matrices, Matrices +@subsection Empty Matrices + +A matrix may have one or both dimensions zero, and operations on empty +matrices are handled as described by Carl de Boor in @cite{An Empty +Exercise}, SIGNUM, Volume 25, pages 2--6, 1990 and C. N. Nett and W. M. +Haddad, in @cite{A System-Theoretic Appropriate Realization of the Empty +Matrix Concept}, IEEE Transactions on Automatic Control, Volume 38, +Number 5, May 1993. Briefly, given a scalar @code{s}, and an @var{m} by +@var{n} matrix @code{M(mxn)}, and an @var{m} by @var{n} empty matrix +@code{[](mxn)} (with either one or both dimensions equal to zero), the +following are true: + +@example +s * [](mxn) = [](mxn) * s = [](mxn) + + [](mxn) + [](mxn) = [](mxn) + + [](0xm) * M(mxn) = [](0xn) + + M(mxn) * [](nx0) = [](mx0) + + [](mx0) * [](0xn) = 0(mxn) +@end example + +By default, dimensions of the empty matrix are now printed along +with the empty matrix symbol, @samp{[]}. For example: + +@example +octave:13> zeros (3, 0) +ans = + +[](3x0) +@end example + +The built-in variable @code{print_empty_dimensions} controls this +behavior (@pxref{User Preferences}). + +Empty matrices may also be used in assignment statements as a convenient +way to delete rows or columns of matrices. +@xref{Assignment Ops, ,Assignment Expressions}. + +@node Ranges, Variables, Matrices, Expressions +@section Ranges +@cindex range expressions +@cindex expression, range + +@opindex : + +A @dfn{range} is a convenient way to write a row vector with evenly +spaced elements. A range constant is defined by the value of the first +element in the range, an optional value for the increment between +elements, and a maximum value which the elements of the range will not +exceed. The base, increment, and limit are separated by colons (the +@samp{:} character) and may contain any arithmetic expressions and +function calls. If the increment is omitted, it is assumed to be 1. +For example, the range + +@example +1 : 5 +@end example + +@noindent +defines the set of values @samp{[ 1 2 3 4 5 ]} (the increment has been +omitted, so it is taken as 1), and the range + +@example +1 : 3 : 5 +@end example + +@noindent +defines the set of values @samp{[ 1 4 ]}. In this case, the base value +is 1, the increment is 3, and the limit is 5. + +Although a range constant specifies a row vector, Octave does @emph{not} +convert range constants to vectors unless it is necessary to do so. +This allows you to write a constant like @samp{1 : 10000} without using +up 80,000 bytes of storage on a typical 32-bit workstation. + +Note that the upper (or lower, if the increment is negative) bound on +the range is not always included in the set of values, and that ranges +defined by floating point values can produce surprising results because +Octave uses floating point arithmetic to compute the values in the +range. If it is important to include the endpoints of a range and the +number of elements is known, you should use the @code{linspace} function +instead (@pxref{Special Matrices}). + +@node Variables, Index Expressions, Ranges, Expressions +@section Variables +@cindex variables, user-defined +@cindex user-defined variables + +Variables let you give names to values and refer to them later. You have +already seen variables in many of the examples. The name of a variable +must be a sequence of letters, digits and underscores, but it may not begin +with a digit. Octave does not enforce a limit on the length of variable +names, but it is seldom useful to have variables with names longer than +about 30 characters. The following are all valid variable names + +@cindex job hunting +@cindex getting a good job +@cindex flying high and fast +@example +x +x15 +__foo_bar_baz__ +fucnrdthsucngtagdjb +@end example + +@noindent +Case is significant in variable names. The symbols @code{a} and +@code{A} are distinct variables. + +A variable name is a valid expression by itself. It represents the +variable's current value. Variables are given new values with +@dfn{assignment operators} and @dfn{increment operators}. +@xref{Assignment Ops, ,Assignment Expressions}. + +A number of variables have special built-in meanings. For example, +@code{PWD} holds the current working directory, and @code{pi} names the +ratio of the circumference of a circle to its diameter. @xref{Built-in +Variables}, for a list of all the predefined variables. Some of these +built-in symbols are constants and may not be changed. Others can be +used and assigned just like all other variables, but their values are +also used or changed automatically by Octave. + +Variables in Octave can be assigned either numeric or string values. +Variables may not be used before they have been given a value. Doing so +results in an error. + +@node Index Expressions, Data Structures, Variables, Expressions +@section Index Expressions + +An @dfn{index expression} allows you to reference or extract selected +elements of a matrix or vector. + +Indices may be scalars, vectors, ranges, or the special operator +@samp{:}, which may be used to select entire rows or columns. + +Vectors are indexed using a single expression. Matrices require two +indices unless the value of the built-in variable +@code{do_fortran_indexing} is @code{"true"}, in which case a matrix may +also be indexed by a single expression (@pxref{User Preferences}). + +Given the matrix + +@example +a = [1, 2; 3, 4] +@end example + +@noindent +all of the following expressions are equivalent + +@example +a (1, [1, 2]) +a (1, 1:2) +a (1, :) +@end example + +@noindent +and select the first row of the matrix. + +A special form of indexing may be used to select elements of a matrix or +vector. If the indices are vectors made up of only ones and zeros, the +result is a new matrix whose elements correspond to the elements of the +index vector that are equal to one. For example, + +@example +a = [1, 2; 3, 4]; +a ([1, 0], :) +@end example + +@noindent +selects the first row of the matrix @samp{a}. + +This operation can be useful for selecting elements of a matrix based on +some condition, since the comparison operators return matrices of ones +and zeros. + +Unfortunately, this special zero-one form of indexing leads to a +conflict with the standard indexing operation. For example, should the +following statements + +@example +a = [1, 2; 3, 4]; +a ([1, 1], :) +@end example + +@noindent +return the original matrix, or the matrix formed by selecting the first +row twice? Although this conflict is not likely to arise very often in +practice, you may select the behavior you prefer by setting the built-in +variable @code{prefer_zero_one_indexing} (@pxref{User Preferences}). + +Finally, indexing a scalar with a vector of ones can be used to create a +vector the same size as the the index vector, with each element equal to +the value of the original scalar. For example, the following statements + +@example +a = 13; +a ([1, 1, 1, 1]) +@end example + +@noindent +produce a vector whose four elements are all equal to 13. + +Similarly, indexing a scalar with two vectors of ones can be used to +create a matrix. For example the following statements + +@example +a = 13; +a ([1, 1], [1, 1, 1]) +@end example + +@noindent +create a 2 by 3 matrix with all elements equal to 13. + +This is an obscure notation and should be avoided. It is better to +use the function @samp{ones} to generate a matrix of the appropriate +size whose elements are all one, and then to scale it to produce the +desired result. @xref{Special Matrices}. + +@node Data Structures, Calling Functions, Index Expressions, Expressions +@section Data Structures +@cindex structures +@cindex data structures + +Octave includes a limited amount of support for organizing data in +structures. The current implementation uses an associative array +with indices limited to strings, but the syntax is more like C-style +structures. Here are some examples of using data structures in Octave. + +Elements of structures can be of any value type. + +@example +octave:1> x.a = 1; x.b = [1, 2; 3, 4]; x.c = "string"; +octave:2> x.a +x.a = 1 +octave:3> x.b +x.b = + + 1 2 + 3 4 + +octave:4> x.c +x.c = string +@end example + +Structures may be copied. + +@example +octave:1> y = x +y = + +<structure: a b c> +@end example + +Note that when the value of a structure is printed, Octave only displays +the names of the elements. This prevents long and confusing output from +large deeply nested structures, but makes it more difficult to view the +values of simple structures, so this behavior may change in a future +version of Octave. + +Since structures are themselves values, structure elements may reference +other structures. The following statements change the value of the +element @code{b} of the structure @code{x} to be a data structure +containing the single element @code{d}, which has a value of 3. + +@example +octave:1> x.b.d = 3 +x.b.d = 3 +octave:2> x.b +x.b = + +<structure: d> + +octave:3> x.b.d +x.b.d = 3 +@end example + +Functions can return structures. For example, the following function +separates the real and complex parts of a matrix and stores them in two +elements of the same structure variable. + +@example +octave:1> function y = f (x) +> y.re = real (x); +> y.im = imag (x); +> endfunction +@end example + +When called with a complex-valued argument, @code{f} returns the data +structure containing the real and imaginary parts of the original +function argument. + +@example +octave:1> f (rand (3) + rand (3) * I); +ans = + +<structure: im re> + +octave:3> ans.im +ans.im = + + 0.093411 0.229690 0.627585 + 0.415128 0.221706 0.850341 + 0.894990 0.343265 0.384018 + +octave:4> ans.re +ans.re = + + 0.56234 0.14797 0.26416 + 0.72120 0.62691 0.20910 + 0.89211 0.25175 0.21081 +@end example + +Function return lists can include structure elements, and they may be +indexed like any other variable. + +@example +octave:1> [x.u, x.s(2:3,2:3), x.v] = svd ([1, 2; 3, 4]) +x.u = + + -0.40455 -0.91451 + -0.91451 0.40455 + +x.s = + + 0.00000 0.00000 0.00000 + 0.00000 5.46499 0.00000 + 0.00000 0.00000 0.36597 + +x.v = + + -0.57605 0.81742 + -0.81742 -0.57605 + +octave:8> x +x = + +<structure: s u v> +@end example + +@findex is_struct + +You can also use the function @code{is_struct} to determine whether a +given value is a data structure. For example + +@example +is_struct (x) +@end example + +@noindent +returns 1 if the value of the variable @var{x} is a data structure. + +This feature should be considered experimental, but you should expect it +to work. Suggestions for ways to improve it are welcome. + +@node Calling Functions, Global Variables, Data Structures, Expressions +@section Calling Functions + +A @dfn{function} is a name for a particular calculation. Because it has +a name, you can ask for it by name at any point in the program. For +example, the function @code{sqrt} computes the square root of a number. + +A fixed set of functions are @dfn{built-in}, which means they are +available in every Octave program. The @code{sqrt} function is one of +these. In addition, you can define your own functions. +@xref{Functions and Scripts}, for information about how to do this. + +@cindex arguments in function call +The way to use a function is with a @dfn{function call} expression, +which consists of the function name followed by a list of +@dfn{arguments} in parentheses. The arguments are expressions which give +the raw materials for the calculation that the function will do. When +there is more than one argument, they are separated by commas. If there +are no arguments, you can omit the parentheses, but it is a good idea to +include them anyway, to clearly indicate that a function call was +intended. Here are some examples: + +@example +sqrt (x^2 + y^2) # @r{One argument} +ones (n, m) # @r{Two arguments} +rand () # @r{No arguments} +@end example + +Each function expects a particular number of arguments. For example, the +@code{sqrt} function must be called with a single argument, the number +to take the square root of: + +@example +sqrt (@var{argument}) +@end example + +Some of the built-in functions take a variable number of arguments, +depending on the particular usage, and their behavior is different +depending on the number of arguments supplied. + +Like every other expression, the function call has a value, which is +computed by the function based on the arguments you give it. In this +example, the value of @code{sqrt (@var{argument})} is the square root of +the argument. A function can also have side effects, such as assigning +the values of certain variables or doing input or output operations. + +Unlike most languages, functions in Octave may return multiple values. +For example, the following statement + +@example +[u, s, v] = svd (a) +@end example + +@noindent +computes the singular value decomposition of the matrix @samp{a} and +assigns the three result matrices to @samp{u}, @samp{s}, and @samp{v}. + +The left side of a multiple assignment expression is itself a list of +expressions, and is allowed to be a list of variable names or index +expressions. See also @ref{Index Expressions}, and @ref{Assignment Ops}. + +@menu +* Call by Value:: +* Recursion:: +@end menu + +@node Call by Value, Recursion, Calling Functions, Calling Functions +@subsection Call by Value + +In Octave, unlike Fortran, function arguments are passed by value, which +means that each argument in a function call is evaluated and assigned to +a temporary location in memory before being passed to the function. +There is currently no way to specify that a function parameter should be +passed by reference instead of by value. This means that it is +impossible to directly alter the value of function parameter in the +calling function. It can only change the local copy within the function +body. For example, the function + +@example +function f (x, n) + while (n-- > 0) + disp (x); + endwhile +endfunction +@end example + +@noindent +displays the value of the first argument @var{n} times. In this +function, the variable @var{n} is used as a temporary variable without +having to worry that its value might also change in the calling +function. Call by value is also useful because it is always possible to +pass constants for any function parameter without first having to +determine that the function will not attempt to modify the parameter. + +The caller may use a variable as the expression for the argument, but +the called function does not know this: it only knows what value the +argument had. For example, given a function called as + +@example +foo = "bar"; +fcn (foo) +@end example + +@noindent +you should not think of the argument as being ``the variable +@code{foo}.'' Instead, think of the argument as the string value, +@code{"bar"}. + +@node Recursion, , Call by Value, Calling Functions +@subsection Recursion +@cindex factorial function + +Recursive function calls are allowed. A @dfn{recursive function} is one +which calls itself, either directly or indirectly. For example, here is +an inefficient@footnote{It would be much better to use @code{prod +(1:n)}, or @code{gamma (n+1)} instead, after first checking to ensure +that the value @code{n} is actually a positive integer.} way to compute +the factorial of a given integer: + +@example +function retval = fact (n) + if (n > 0) + retval = n * fact (n-1); + else + retval = 1; + endif +endfunction +@end example + +This function is recursive because it calls itself directly. It +eventually terminates because each time it calls itself, it uses an +argument that is one less than was used for the previous call. Once the +argument is no longer greater than zero, it does not call itself, and +the recursion ends. + +There is currently no limit on the recursion depth, so infinite +recursion is possible. If this happens, Octave will consume more and +more memory attempting to store intermediate values for each function +call context until there are no more resources available. This is +obviously undesirable, and will probably be fixed in some future version +of Octave by allowing users to specify a maximum allowable recursion +depth. + +@cindex global variables +@cindex variables, global + +@node Global Variables, Keywords, Calling Functions, Expressions +@section Global Variables + +A variable that has been declared @dfn{global} may be accessed from +within a function body without having to pass it as a formal parameter. + +A variable may be declared global using a @code{global} declaration +statement. The following statements are all global declarations. + +@example +global a +global b = 2 +global c = 3, d, e = 5 +@end example + +It is necessary declare a variable as global within a function body in +order to access it. For example, + +@example +global x +function f () +x = 1; +endfunction +f () +@end example + +@noindent +does @emph{not} set the value of the global variable @samp{x} to 1. In +order to change the value of the global variable @samp{x}, you must also +declare it to be global within the function body, like this + +@example +function f () + global x; + x = 1; +endfunction +@end example + +Passing a global variable in a function parameter list will +make a local copy and not modify the global value. For example: + +@example +octave:1> function f (x) +> x = 3 +> endfunction +octave:2> global x = 0 +octave:3> x # This is the value of the global variable. +x = 0 +octave:4> f (x) +x = 3 # The value of the local variable x is 3. +octave:5> x # But it was a *copy* so the global variable +x = 0 # remains unchanged. +@end example + +@node Keywords, Arithmetic Ops, Global Variables, Expressions +@section Keywords +@cindex keywords + +The following identifiers are keywords, and may not be used as variable +or function names: + +@example +break endfor function return +continue endfunction global while +else endif gplot +elseif endwhile gsplot +end for if +@end example + +The following command-like functions are also keywords, and may not be +used as variable or function names: + +@example +casesen document history set +cd edit_history load show +clear help ls who +dir format run_history save +@end example + +@node Arithmetic Ops, Comparison Ops, Keywords, Expressions +@section Arithmetic Operators +@cindex arithmetic operators +@cindex operators, arithmetic +@cindex addition +@cindex subtraction +@cindex multiplication +@cindex matrix multiplication +@cindex division +@cindex quotient +@cindex negation +@cindex unary minus +@cindex exponentiation +@cindex transpose +@cindex Hermitian operator +@cindex transpose, complex-conjugate +@cindex complex-conjugate transpose + +@opindex + +@opindex - +@opindex * +@opindex / +@opindex \ +@opindex ** +@opindex ^ +@opindex ' +@opindex .+ +@opindex .- +@opindex .* +@opindex ./ +@opindex .\ +@opindex .** +@opindex .^ +@opindex .' + +The following arithmetic operators are available, and work on scalars +and matrices. + +@table @code +@item @var{x} + @var{y} +Addition. If both operands are matrices, the number of rows and columns +must both agree. If one operand is a scalar, its value is added to +all the elements of the other operand. + +@item @var{x} .+ @var{y} +Element by element addition. This operator is equivalent to @code{+}. + +@item @var{x} - @var{y} +Subtraction. If both operands are matrices, the number of rows and +columns of both must agree. + +@item @var{x} .- @var{y} +Element by element subtraction. This operator is equivalent to @code{-}. + +@item @var{x} * @var{y} +Matrix multiplication. The number of columns of @samp{x} must agree +with the number of rows of @samp{y}. + +@item @var{x} .* @var{y} +Element by element multiplication. If both operands are matrices, the +number of rows and columns must both agree. + +@item @var{x} / @var{y} +Right division. This is conceptually equivalent to the expression + +@example +(inverse (y') * x')' +@end example + +@noindent +but it is computed without forming the inverse of @samp{y'}. + +If the system is not square, or if the coefficient matrix is singular, +a minimum norm solution is computed. + +@item @var{x} ./ @var{y} +Element by element right division. + +@item @var{x} \ @var{y} +Left division. This is conceptually equivalent to the expression + +@example +inverse (x) * y +@end example + +@noindent +but it is computed without forming the inverse of @samp{x}. + +If the system is not square, or if the coefficient matrix is singular, +a minimum norm solution is computed. + +@item @var{x} .\ @var{y} +Element by element left division. Each element of @samp{y} is divided +by each corresponding element of @samp{x}. + +@item @var{x} ^ @var{y} +@itemx @var{x} ** @var{y} +Power operator. If @var{x} and @var{y} are both scalars, this operator +returns @var{x} raised to the power @var{y}. If @var{x} is a scalar and +@var{y} is a square matrix, the result is computed using an eigenvalue +expansion. If @var{x} is a square matrix. the result is computed by +repeated multiplication if @var{y} is an integer, and by an eigenvalue +expansion if @var{y} is not an integer. An error results if both +@var{x} and @var{y} are matrices. + +The implementation of this operator needs to be improved. + +@item @var{x} .^ @var{y} +@item @var{x} .** @var{y} +Element by element power operator. If both operands are matrices, the +number of rows and columns must both agree. + +@item -@var{x} +Negation. + +@item +@var{x} +Unary plus. This operator has no effect on the operand. + +@item @var{x}' +Complex conjugate transpose. For real arguments, this operator is the +same as the transpose operator. For complex arguments, this operator is +equivalent to the expression + +@example +conj (x.') +@end example + +@item @var{x}.' +Transpose. +@end table + +Note that because Octave's element by element operators begin with a +@samp{.}, there is a possible ambiguity for statements like + +@example +1./m +@end example + +@noindent +because the period could be interpreted either as part of the constant +or as part of the operator. To resolve this conflict, Octave treats the +expression as if you had typed + +@example +(1) ./ m +@end example + +@noindent +and not + +@example +(1.) / m +@end example + +@noindent +Although this is inconsistent with the normal behavior of Octave's +lexer, which usually prefers to break the input into tokens by +preferring the longest possible match at any given point, it is more +useful in this case. + +@node Comparison Ops, Boolean Expressions, Arithmetic Ops, Expressions +@section Comparison Operators +@cindex comparison expressions +@cindex expressions, comparison +@cindex relational operators +@cindex operators, relational +@cindex less than operator +@cindex greater than operator +@cindex equality operator +@cindex tests for equality +@cindex equality, tests for + +@opindex < +@opindex <= +@opindex == +@opindex >= +@opindex > +@opindex != +@opindex ~= +@opindex <> + +@dfn{Comparison operators} compare numeric values for relationships +such as equality. They are written using +@emph{relational operators}, which are a superset of those in C. + +All of Octave's comparison operators return a value of 1 if the +comparison is true, or 0 if it is false. For matrix values, they all +work on an element-by-element basis. For example, evaluating the +expression + +@example +[1, 2; 3, 4] == [1, 3; 2, 4] +@end example + +@noindent +returns the result + +@example +ans = + + 1 0 + 0 1 +@end example + +@table @code +@item @var{x} < @var{y} +True if @var{x} is less than @var{y}. + +@item @var{x} <= @var{y} +True if @var{x} is less than or equal to @var{y}. + +@item @var{x} == @var{y} +True if @var{x} is equal to @var{y}. + +@item @var{x} >= @var{y} +True if @var{x} is greater than or equal to @var{y}. + +@item @var{x} > @var{y} +True if @var{x} is greater than @var{y}. + +@item @var{x} != @var{y} +@itemx @var{x} ~= @var{y} +@itemx @var{x} <> @var{y} +True if @var{x} is not equal to @var{y}. +@end table + +For matrix and vector arguments, the above table should be read as +``an element of the result matrix (vector) is true if the corresponding +elements of the argument matrices (vectors) satisfy the specified +condition'' + +String comparisons should be performed with the @code{strcmp} function, +not with the comparison operators listed above. +@xref{Calling Functions}. + +@node Boolean Expressions, Assignment Ops, Comparison Ops, Expressions +@section Boolean Expressions +@cindex expressions, boolean +@cindex boolean expressions +@cindex expressions, logical +@cindex logical expressions +@cindex operators, boolean +@cindex boolean operators +@cindex logical operators +@cindex operators, logical +@cindex and operator +@cindex or operator +@cindex not operator + +@menu +* Element-by-element Boolean Operators:: +* Short-circuit Boolean Operators:: +@end menu + +@node Element-by-element Boolean Operators, Short-circuit Boolean Operators, Boolean Expressions, Boolean Expressions +@subsection Element-by-element Boolean Operators +@cindex element-by-element evaluation + +@opindex | +@opindex & +@opindex ~ +@opindex ! + +An element-by-element @dfn{boolean expression} is a combination of +comparison expressions or matching expressions, using the boolean +operators ``or'' (@samp{|}), ``and'' (@samp{&}), and ``not'' (@samp{!}), +along with parentheses to control nesting. The truth of the boolean +expression is computed by combining the truth values of the +corresponding elements of the component expressions. A value is +considered to be false if it is zero, and true otherwise. + +Element-by-element boolean expressions can be used wherever comparison +expressions can be used. They can be used in @code{if} and @code{while} +statements. However, before being used in the condition of an @code{if} +or @code{while} statement, an implicit conversion from a matrix value to +a scalar value occurs using the equivalent of +@code{all (all (@var{x}))}. That is, a value used as the condition in an +@code{if} or @code{while} statement is only true if @emph{all} of its +elements are nonzero. + +Like comparison operations, each element of an element-by-element +boolean expression also has a numeric value (1 if true, 0 if false) that +comes into play if the result of the boolean expression is stored in a +variable, or used in arithmetic. + +Here are descriptions of the three element-by-element boolean operators. + +@table @code +@item @var{boolean1} & @var{boolean2} +Elements of the result are true if both corresponding elements of +@var{boolean1} and @var{boolean2} are true. + +@item @var{boolean1} | @var{boolean2} +Elements of the result are true if either of the corresponding elements +of @var{boolean1} or @var{boolean2} is true. + +@item ! @var{boolean} +@itemx ~ @var{boolean} +Each element of the result is true if the corresponding element of +@var{boolean} is false. +@end table + +For matrix operands, these operators work on an element-by-element +basis. For example, the expression + +@example +[1, 0; 0, 1] & [1, 0; 2, 3] +@end example + +@noindent +returns a two by two identity matrix. + +For the binary operators, the dimensions of the operands must conform if +both are matrices. If one of the operands is a scalar and the other a +matrix, the operator is applied to the scalar and each element of the +matrix. + +For the binary element-by-element boolean operators, both subexpressions +@var{boolean1} and @var{boolean2} are evaluated before computing the +result. This can make a difference when the expressions have side +effects. For example, in the expression + +@example +a & b++ +@end example + +@noindent +the value of the variable @var{b} is incremented even if the variable +@var{a} is zero. + +This behavior is necessary for the boolean operators to work as +described for matrix-valued operands. + +@node Short-circuit Boolean Operators, , Element-by-element Boolean Operators, Boolean Expressions +@subsection Short-circuit Boolean Operators +@cindex short-circuit evaluation + +@opindex || +@opindex && + +Combined with the implicit conversion to scalar values in @code{if} and +@code{while} conditions, Octave's element-by-element boolean operators +are often sufficient for performing most logical operations. However, +it is sometimes desirable to stop evaluating a boolean expression as +soon as the overall truth value can be determined. Octave's +@dfn{short-circuit} boolean operators work this way. + +@table @code +@item @var{boolean1} && @var{boolean2} +The expression @var{boolean1} is evaluated and converted to a scalar +using the equivalent of the operation @code{all (all (@var{boolean1}))}. +If it is false, the result of the expression is 0. If it is true, the +expression @var{boolean2} is evaluated and converted to a scalar +using the equivalent of the operation @code{all (all (@var{boolean1}))}. +If it is true, the result of the expression is 1. Otherwise, the result +of the expression is 0. + +@item @var{boolean1} || @var{boolean2} +The expression @var{boolean1} is evaluated and converted to a scalar +using the equivalent of the operation @code{all (all (@var{boolean1}))}. +If it is true, the result of the expression is 1. If it is false, the +expression @var{boolean2} is evaluated and converted to a scalar +using the equivalent of the operation @code{all (all (@var{boolean1}))}. +If it is true, the result of the expression is 1. Otherwise, the result +of the expression is 0. +@end table + +The fact that both operands may not be evaluated before determining the +overall truth value of the expression can be important. For example, in +the expression + +@example +a && b++ +@end example + +@noindent +the value of the variable @var{b} is only incremented if the variable +@var{a} is nonzero. + +This can be used to write somewhat more concise code. For example, it +is possible write + +@example +function f (a, b, c) + if (nargin > 2 && isstr (c)) + ... +@end example + +@noindent +instead of having to use two @code{if} statements to avoid attempting to +evaluate an argument that doesn't exist. + +@example +function f (a, b, c) + if (nargin > 2) + if (isstr (c)) + ... +@end example + +@node Assignment Ops, Increment Ops, Boolean Expressions, Expressions +@section Assignment Expressions +@cindex assignment expressions +@cindex assignment operators +@cindex operators, assignment +@cindex expressions, assignment + +@opindex = + +An @dfn{assignment} is an expression that stores a new value into a +variable. For example, the following expression assigns the value 1 to +the variable @code{z}: + +@example +z = 1 +@end example + +After this expression is executed, the variable @code{z} has the value 1. +Whatever old value @code{z} had before the assignment is forgotten. + +Assignments can store string values also. For example, the following +expression would store the value @code{"this food is good"} in the +variable @code{message}: + +@example +thing = "food" +predicate = "good" +message = [ "this " , thing , " is " , predicate ] +@end example + +@noindent +(This also illustrates concatenation of strings.) + +The @samp{=} sign is called an @dfn{assignment operator}. It is the +simplest assignment operator because the value of the right-hand +operand is stored unchanged. + +@cindex side effect +Most operators (addition, concatenation, and so on) have no effect +except to compute a value. If you ignore the value, you might as well +not use the operator. An assignment operator is different. It does +produce a value, but even if you ignore the value, the assignment still +makes itself felt through the alteration of the variable. We call this +a @dfn{side effect}. + +@cindex lvalue +The left-hand operand of an assignment need not be a variable +(@pxref{Variables}). It can also be an element of a matrix +(@pxref{Index Expressions}) or a list of return values +(@pxref{Calling Functions}). These are all called @dfn{lvalues}, which +means they can appear on the left-hand side of an assignment operator. +The right-hand operand may be any expression. It produces the new value +which the assignment stores in the specified variable, matrix element, +or list of return values. + +It is important to note that variables do @emph{not} have permanent types. +The type of a variable is simply the type of whatever value it happens +to hold at the moment. In the following program fragment, the variable +@code{foo} has a numeric value at first, and a string value later on: + +@example +octave:13> foo = 1 +foo = 1 +octave:13> foo = "bar" +foo = bar +@end example + +@noindent +When the second assignment gives @code{foo} a string value, the fact that +it previously had a numeric value is forgotten. + +Assigning an empty matrix @samp{[]} works in most cases to allow you to +delete rows or columns of matrices and vectors. @xref{Empty Matrices}. +For example, given a 4 by 5 matrix @var{A}, the assignment + +@example +A (3, :) = [] +@end example + +@noindent +deletes the third row of @var{A}, and the assignment + +@example +A (:, 1:2:5) = [] +@end example + +@noindent +deletes the first, third, and fifth columns. + +An assignment is an expression, so it has a value. Thus, @code{z = 1} +as an expression has the value 1. One consequence of this is that you +can write multiple assignments together: + +@example +x = y = z = 0 +@end example + +@noindent +stores the value 0 in all three variables. It does this because the +value of @code{z = 0}, which is 0, is stored into @code{y}, and then +the value of @code{y = z = 0}, which is 0, is stored into @code{x}. + +This is also true of assignments to lists of values, so the following is +a valid expression + +@example +[a, b, c] = [u, s, v] = svd (a) +@end example + +@noindent +that is exactly equivalent to + +@example +[u, s, v] = svd (a) +a = u +b = s +c = v +@end example + +In expressions like this, the number of values in each part of the +expression need not match. For example, the expression + +@example +[a, b, c, d] = [u, s, v] = svd (a) +@end example + +@noindent +is equivalent to the expression above, except that the value of the +variable @samp{d} is left unchanged, and the expression + +@example +[a, b] = [u, s, v] = svd (a) +@end example + +@noindent +is equivalent to + +@example +[u, s, v] = svd (a) +a = u +b = s +@end example + +You can use an assignment anywhere an expression is called for. For +example, it is valid to write @code{x != (y = 1)} to set @code{y} to 1 +and then test whether @code{x} equals 1. But this style tends to make +programs hard to read. Except in a one-shot program, you should rewrite +it to get rid of such nesting of assignments. This is never very hard. + +@cindex increment operator +@cindex decrement operator +@cindex operators, increment +@cindex operators, decrement + +@opindex ++ +@opindex -- + +@node Increment Ops, Operator Precedence, Assignment Ops, Expressions +@section Increment Operators + +@emph{Increment operators} increase or decrease the value of a variable +by 1. The operator to increment a variable is written as @samp{++}. It +may be used to increment a variable either before or after taking its +value. + +For example, to pre-increment the variable @var{x}, you would write +@code{++@var{x}}. This would add one to @var{x} and then return the new +value of @var{x} as the result of the expression. It is exactly the +same as the expression @code{@var{x} = @var{x} + 1}. + +To post-increment a variable @var{x}, you would write @code{@var{x}++}. +This adds one to the variable @var{x}, but returns the value that +@var{x} had prior to incrementing it. For example, if @var{x} is equal +to 2, the result of the expression @code{@var{x}++} is 2, and the new +value of @var{x} is 3. + +For matrix and vector arguments, the increment and decrement operators +work on each element of the operand. + +Here is a list of all the increment and decrement expressions. + +@table @code +@item ++@var{x} +This expression increments the variable @var{x}. The value of the +expression is the @emph{new} value of @var{x}. It is equivalent to the +expression @code{@var{x} = @var{x} + 1}. + +@item --@var{x} +This expression decrements the variable @var{x}. The value of the +expression is the @emph{new} value of @var{x}. It is equivalent to the +expression @code{@var{x} = @var{x} - 1}. + +@item @var{x}++ +This expression causes the variable @var{x} to be incremented. The +value of the expression is the @emph{old} value of @var{x}. + +@item @var{x}-- +This expression causes the variable @var{x} to be decremented. The +value of the expression is the @emph{old} value of @var{x}. +@end table + +It is not currently possible to increment index expressions. For +example, you might expect that the expression @code{@var{v}(4)++} would +increment the fourth element of the vector @var{v}, but instead it +results in a parse error. This problem may be fixed in a future +release of Octave. + +@cindex operator precedence + +@node Operator Precedence, , Increment Ops, Expressions +@section Operator Precedence + +@dfn{Operator precedence} determines how operators are grouped, when +different operators appear close by in one expression. For example, +@samp{*} has higher precedence than @samp{+}. Thus, the expression +@code{a + b * c} means to multiply @code{b} and @code{c}, and then add +@code{a} to the product (i.e., @code{a + (b * c)}). + +You can overrule the precedence of the operators by using parentheses. +You can think of the precedence rules as saying where the parentheses +are assumed if you do not write parentheses yourself. In fact, it is +wise to use parentheses whenever you have an unusual combination of +operators, because other people who read the program may not remember +what the precedence is in this case. You might forget as well, and then +you too could make a mistake. Explicit parentheses will help prevent +any such mistake. + +When operators of equal precedence are used together, the leftmost +operator groups first, except for the assignment, and exponentiation +operators, which group in the opposite order. Thus, the expression +@code{a - b + c} groups as @code{(a - b) + c}, but the expression +@code{a = b = c} groups as @code{a = (b = c)}. + +The precedence of prefix unary operators is important when another +operator follows the operand. For example, @code{-x^2} means +@code{-(x^2)}, because @samp{-} has lower precedence than @samp{^}. + +Here is a table of the operators in Octave, in order of increasing +precedence. + +@table @code +@item statement separators +@samp{;}, @samp{,}. + +@item assignment +@samp{=}. This operator groups right to left. + +@item logical "or" and "and" +@samp{||}, @samp{&&}. + +@item element-wise "or" and "and" +@samp{|}, @samp{&}. + +@item relational +@samp{<}, @samp{<=}, @samp{==}, @samp{>=}, @samp{>}, @samp{!=}, +@samp{~=}, @samp{<>}. + +@item colon +@samp{:}. + +@item add, subtract +@samp{+}, @samp{-}. + +@item multiply, divide +@samp{*}, @samp{/}, @samp{\}, @samp{.\}, @samp{.*}, @samp{./}. + +@item transpose +@samp{'}, @samp{.'} + +@item unary plus, minus, increment, decrement, and ``not'' +@samp{+}, @samp{-}, @samp{++}, @samp{--}, @samp{!}, @samp{~}. + +@item exponentiation +@samp{^}, @samp{**}, @samp{.^}, @samp{.**}. +@end table
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/extend.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,156 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Adding New Functions +@chapter Adding New Functions +@cindex Functions + +The following is not complete, but should help get you started and +give you some idea about why things are they way they are. + +Here's what you need to do to add a new function (I'll use svd() as an +example): + + 1. Add the name of the new function to the general_functions list in + builtins.cc: + + static builtin_general_functions general_functions[] = + { + ... + + { "svd", 2, 3, builtin_svd, + "[U, S, V] = svd (X): return SVD of X\n", }, + + ... + }; + + The builtin_general_functions struct is defined in builtns.h: + + struct builtin_general_functions + { + char *name; + int nargin_max; + int nargout_max; + General_fcn general_fcn; + char *help_string; + }; + + name is what the user types (e.g. `svd'); + + nargin_max and nargout_max are the maximum number of input and + output arguments. These are not really important. I had + originally planned to use them to allow Octave to do some + checking to see if the user had supplied the correct number of + arguments, but that doesn't really work very well. It seems + better to have each function check (since different numbers of + input arguments may mean different things). + + Note: nargin == 1 means that the function takes no arguments (just + like C, the first argument is (or should be, anyway) the function + name). Also, -1 is shorthand for infinity. + + general_fcn is the function you need to define to do the real + work. Usually called builtin_foo, for function foo. More about + the form of this function is given below. + + help_string is the message that the user will get if he types + `help svd'. + + Yes, the initialization of this structure is a bit clumsy. I'm + probably going to try to fix that at some point, but don't really + know exactly how and haven't had time to do it right yet. + + 2. Write the function that does all the work. I've adopted the + following convention: + + * Declare the function in g-builtins.h. All `general' + functions take the same arguments: + + builtin_svd (const tree_constant *args, int nargin, int nargout) + + - args: a vector of tree_constants, which is the basic + data structure for values in Octave. Currently, a + tree_constant can be a real or complex scalar or matrix, + a range, or a string. + + - nargin: the number of arguments the user provided plus + one. args[0] is supposed to hold the function name, but + I'm not sure that that's always true yet. + + - nargout: the number of arguments the user provided on + the left side of an assignment, or one if no assignment + is being done (because of the implicit assignment to ans + that will occur). + + * Define the function in g-builtins.cc. Usually, the function + in g-builtins.cc only contains simple checks to see if the + correct number of arguments have been supplied and then a + call to the function that REALLY :-) does all the work. + + If the function is small, it's probably reasonable to define + it in tc-extras.cc. + + If the function is not small, or if it depends on external + fortran code, it is probably best to put it in its own file + (for example, f-svd.cc). If dynamic linking is ever really + made to work, it will be important for functions to be + implemented this way. + + To make it easier to make all of this work in the future, + calls are written using the DLD_FUNC macro defined at the top + of g-builtins.cc. For example: + + DLD_BUILTIN (args, nargin, nargout, svd, + retval = svd (args, nargin, nargout);) + + If dynamic linking is being used, this expands to + + return octave_dld_tc2_and_go (args, nargin, nargout, "svd", \ + "builtin_svd_2", "f-svd.o")); + + which is a call to a function that will take care of patching + in the function builtin_svd_2, which is defined in the file + f-svd.cc (corresponding to the object file f-svd.o). + + Otherwise, it simply expands to + + retval = svd (args, nargin, nargout); + + (a function that is also defined in f-svd.cc). + + * If the function is defined in a separate file, like f-svd.cc, + it should be implemented like the others that already exist. + The code like + + #ifdef WITH_DLD + tree_constant * + builtin_svd_2 (tree_constant *args, int nargin, int nargout) + { + return svd (args, nargin, nargout); + } + #endif + + is just a hook for dynamic loading. It was implemented this + way so that the names of all the functions that are to be + loaded dynamically would have consistent form (so that they + could easily be constructed from the name that the user + types). + + The rest of the code defined in this file does the real + work. In the case of svd, it uses some C++ classes to call + the required Fortran subroutines. The class interfaces are + defined in liboctave/Matrix.h, and the class definitions are + (for things like SVD, HESS, LU, EIG, etc.) are in + Matrix-ext.cc. + + 3. If you add a new file (like f-svd.cc), don't forget to add it to + the list of files in Makefile.in, then use configure to update + the Makefile. + + +You should use the error reporting functions defined in error.{h,cc} +instead of writing messages directly to cout or cerr. + +That way, it will be easier to maintain a consistent look to the +warning and error messages.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/fn-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,8 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Function Index, Operator Index, Variable Index, Top +@unnumbered Function Index + +@printindex fn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/foo.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,6 @@ +\input texinfo +@setfilename foo.info +@settitle Foo +@node A, B, C, D +@chapter A +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/func.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,736 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Functions and Scripts, Built-in Variables, Statements, Top +@chapter Functions and Script Files +@cindex defining functions +@cindex user-defined functions +@cindex functions, user-defined +@cindex script files + +Complicated Octave programs can often be simplified by defining +functions. Functions can be defined directly on the command line during +interactive Octave sessions, or in external files, and can be called just +like built-in ones. + +@menu +* Defining Functions:: +* Multiple Return Values:: +* Variable-length Argument Lists:: +* Variable-length Return Lists:: +* Returning From a Function:: +* Function Files:: +* Script Files:: +* Dynamically Linked Functions:: +* Organization of Functions:: +@end menu + +@node Defining Functions, Multiple Return Values, Functions and Scripts, Functions and Scripts +@section Defining Functions + +In its simplest form, the definition of a function named @var{name} +looks like this: + +@example +@group +function @var{name} + @var{body} +endfunction +@end group +@end example + +@noindent +A valid function name is like a valid variable name: a sequence of +letters, digits and underscores, not starting with a digit. Functions +share the same pool of names as variables. + +The function @var{body} consists of Octave statements. It is the +most important part of the definition, because it says what the function +should actually @emph{do}. + +For example, here is a function that, when executed, will ring the bell +on your terminal (assuming that it is possible to do so): + +@example +@group +function wakeup + printf ("\a"); +endfunction +@end group +@end example + +The @code{printf} statement (@pxref{Input and Output}) simply tells +Octave to print the string @code{"\a"}. The special character @samp{\a} +stands for the alert character (ASCII 7). @xref{String Constants}. + +Once this function is defined, you can ask Octave to evaluate it by +typing the name of the function. + +Normally, you will want to pass some information to the functions you +define. The syntax for passing parameters to a function in Octave is + +@example +@group +function @var{name} (@var{arg-list}) + @var{body} +endfunction +@end group +@end example + +@noindent +where @var{arg-list} is a comma-separated list of the function's +arguments. When the function is called, the argument names are used to +hold the argument values given in the call. The list of arguments may +be empty, in which case this form is equivalent to the one shown above. + +To print a message along with ringing the bell, you might modify the +@code{beep} to look like this: + +@example +@group +function wakeup (message) + printf ("\a%s\n", message); +endfunction +@end group +@end example + +Calling this function using a statement like this + +@example +wakeup ("Rise and shine!"); +@end example + +@noindent +will cause Octave to ring your terminal's bell and print the message +@samp{Rise and shine!}, followed by a newline character (the @samp{\n} +in the first argument to the @code{printf} statement). + +In most cases, you will also want to get some information back from the +functions you define. Here is the syntax for writing a function that +returns a single value: + +@example +@group +function @var{ret-var} = @var{name} (@var{arg-list}) + @var{body} +endfunction +@end group +@end example + +@noindent +The symbol @var{ret-var} is the name of the variable that will hold the +value to be returned by the function. This variable must be defined +before the end of the function body in order for the function to return +a value. + +For example, here is a function that computes the average of the +elements of a vector: + +@example +@group +function retval = avg (v) + retval = sum (v) / length (v); +endfunction +@end group +@end example + +If we had written @code{avg} like this instead, + +@example +@group +function retval = avg (v) + if (is_vector (v)) + retval = sum (v) / length (v); + endif +endfunction +@end group +@end example + +@noindent +and then called the function with a matrix instead of a vector as the +argument, Octave would have printed an error message like this: + +@example +@group +error: `retval' undefined near line 1 column 10 +error: evaluating index expression near line 7, column 1 +@end group +@end example + +@noindent +because the body of the @code{if} statement was never executed, and +@code{retval} was never defined. To prevent obscure errors like this, +it is a good idea to always make sure that the return variables will +always have values, and to produce meaningful error messages when +problems are encountered. For example, @code{avg} could have been +written like this: + +@example +@group +function retval = avg (v) + retval = 0; + if (is_vector (v)) + retval = sum (v) / length (v); + else + error ("avg: expecting vector argument"); + endif +endfunction +@end group +@end example + +There is still one additional problem with this function. What if it is +called without an argument? Without additional error checking, Octave +will probably print an error message that won't really help you track +down the source of the error. To allow you to catch errors like this, +Octave provides each function with an automatic variable called +@code{nargin}. Each time a function is called, @code{nargin} is +automatically initialized to the number of arguments that have actually +been passed to the function. For example, we might rewrite the +@code{avg} function like this: +@vindex nargout + +@example +@group +function retval = avg (v) + retval = 0; + if (nargin != 1) + error ("usage: avg (vector)"); + endif + if (is_vector (v)) + retval = sum (v) / length (v); + else + error ("avg: expecting vector argument"); + endif +endfunction +@end group +@end example + +Although Octave does not automatically report an error if you call a +function with more arguments than expected, doing so probably indicates +that something is wrong. Octave also does not automatically report an +error if a function is called with too few arguments, but any attempt to +use a variable that has not been given a value will result in an error. +To avoid such problems and to provide useful messages, we check for both +possibilities and issue our own error message. + +The body of a user-defined function can contain a @code{return} +statement. This statement returns control to the rest of the Octave +program. A @code{return} statement is assumed at the end of every +function definition. + +@node Multiple Return Values, Variable-length Argument Lists, Defining Functions, Functions and Scripts +@section Multiple Return Values + +Unlike many other computer languages, Octave allows you to define +functions that return more than one value. The syntax for defining +functions that return multiple values is + +@example +function [@var{ret-list}] = @var{name} (@var{arg-list}) + @var{body} +endfunction +@end example + +@noindent +where @var{name}, @var{arg-list}, and @var{body} have the same meaning +as before, and @var{ret-list} is a comma-separated list of variable +names that will hold the values returned from the function. The list of +return values must have at least one element. If @var{ret-list} has +only one element, this form of the @code{function} statement is +equivalent to the form described in the previous section. + +Here is an example of a function that returns two values, the maximum +element of a vector and the index of its first occurrence in the vector. + +@example +@group +function [max, idx] = vmax (v) + idx = 1; + max = v (idx); + for i = 2:length (v) + if (v (i) > max) + max = v (i); + idx = i; + endif + endfor +endfunction +@end group +@end example + +In this particular case, the two values could have been returned as +elements of a single array, but that is not always possible or +convenient. The values to be returned may not have compatible +dimensions, and it is often desirable to give the individual return +values distinct names. + +In addition to setting @code{nargin} each time a function is called, +Octave also automatically initializes @code{nargout} to the number of +values that are expected to be returned. This allows you to write +functions that behave differently depending on the number of values that +the user of the function has requested. The implicit assignment to the +built-in variable @code{ans} does not figure in the count of output +arguments, so the value of @code{nargout} may be zero. + +The @code{svd} and @code{lu} functions are examples of built-in +functions that behave differently depending on the value of +@code{nargout}. + +It is possible to write functions that only set some return values. For +example, calling the function + +@example +function [x, y, z] = f () + x = 1; + z = 2; +endfunction +@end example + +@noindent +as + +@example +[a, b, c] = f () +@end example + +@noindent +produces: + +@example +a = 1 + +b = [](0x0) + +c = 2 +@end example + +@noindent +provided that the built-in variable @code{define_all_return_values} is +nonzero. @xref{Built-in Variables}. + +@node Variable-length Argument Lists, Variable-length Return Lists, Multiple Return Values, Functions and Scripts +@section Variable-length Argument Lists +@cindex Variable-length argument lists +@cindex @code{...} +@findex va_arg +@findex va_start + +Octave has a real mechanism for handling functions that take an +unspecified number of arguments, so it is not necessary to place an +upper bound on the number of optional arguments that a function can +accept. + +Here is an example of a function that uses the new syntax to print a +header followed by an unspecified number of values: + +@example +function foo (heading, ...) + disp (heading); + va_start (); + while (--nargin) + disp (va_arg ()); + endwhile +endfunction +@end example + +The ellipsis that marks the variable argument list may only appear once +and must be the last element in the list of arguments. + +Calling @code{va_start()} positions an internal pointer to the first +unnamed argument and allows you to cycle through the arguments more than +once. It is not necessary to call @code{va_start()} if you do not plan +to cycle through the arguments more than once. + +The function @code{va_arg()} returns the value of the next available +argument and moves the internal pointer to the next argument. It is an +error to call @code{va_arg()} when there are no more arguments +available. + +Sometimes it is useful to be able to pass all unnamed arguments to +another function. The keyword @var{all_va_args} makes this very easy to +do. For example, given the functions + +@example +function f (...) + while (nargin--) + disp (va_arg ()) + endwhile +endfunction +function g (...) + f ("begin", all_va_args, "end") +endfunction +@end example + +@noindent +the statement + +@example +g (1, 2, 3) +@end example + +@noindent +prints + +@example +begin +1 +2 +3 +end +@end example + +The keyword @code{all_va_args} always stands for the entire list of +optional argument, so it is possible to use it more than once within the +same function without having to call @code{va_start ()}. It can only +be used within functions that take a variable number of arguments. It +is an error to use it in other contexts. + +@node Variable-length Return Lists, Returning From a Function, Variable-length Argument Lists, Functions and Scripts +@section Variable-length Return Lists +@cindex Variable-length return lists +@cindex @code{...} +@findex vr_val + +Octave also has a real mechanism for handling functions that return an +unspecified number of values, so it is no longer necessary to place an +upper bound on the number of outputs that a function can produce. + +Here is an example of a function that uses the new syntax to produce +@var{n} values: + +@example +function [...] = foo (n, x) + for i = 1:n + vr_val (i * x); + endfor +endfunction +@end example + +Each time @code{vr_val()} is called, it places the value of its argument +at the end of the list of values to return from the function. Once +@code{vr_val()} has been called, there is no way to go back to the +beginning of the list and rewrite any of the return values. + +As with variable argument lists, the ellipsis that marks the variable +return list may only appear once and must be the last element in the +list of returned values. + +@node Returning From a Function, Function Files, Variable-length Return Lists, Functions and Scripts +@section Returning From a Function + +The body of a user-defined function can contain a @code{return} statement. +This statement returns control to the rest of the Octave program. It +looks like this: + +@example +return +@end example + +Unlike the @code{return} statement in C, Octave's @code{return} +statement cannot be used to return a value from a function. Instead, +you must assign values to the list of return variables that are part of +the @code{function} statement. The @code{return} statement simply makes +it easier to exit a function from a deeply nested loop or conditional +statement. + +Here is an example of a function that checks to see if any elements of a +vector are nonzero. + +@example +@group +function retval = any_nonzero (v) + retval = 0; + for i = 1:length (v) + if (v (i) != 0) + retval = 1; + return; + endif + endfor + printf ("no nonzero elements found\n"); +endfunction +@end group +@end example + +Note that this function could not have been written using the +@code{break} statement to exit the loop once a nonzero value is found +without adding extra logic to avoid printing the message if the vector +does contain a nonzero element. + +@node Function Files, Script Files, Returning From a Function, Functions and Scripts +@section Function Files +@cindex function file + +Except for simple one-shot programs, it is not practical to have to +define all the functions you need each time you need them. Instead, you +will normally want to save them in a file so that you can easily edit +them, and save them for use at a later time. + +Octave does not require you to load function definitions from files +before using them. You simply need to put the function definitions in a +place where Octave can find them. + +When Octave encounters an identifier that is undefined, it first looks +for variables or functions that are already compiled and currently +listed in its symbol table. If it fails to find a definition there, it +searches the list of directories specified by the built-in variable +@code{LOADPATH} for files ending in @file{.m} that have the same base +name as the undefined identifier.@footnote{The @samp{.m} suffix was +chosen for compatibility with @sc{Matlab}.} @xref{User Preferences} +for a description of @code{LOADPATH}. Once Octave finds a file +with a name that matches, the contents of the file are read. If it +defines a @emph{single} function, it is compiled and executed. +@xref{Script Files}, for more information about how you can define more +than one function in a single file. + +When Octave defines a function from a function file, it saves the full +name of the file it read and the time stamp on the file. After +that, it checks the time stamp on the file every time it needs the +function. If the time stamp indicates that the file has changed since +the last time it was read, Octave reads it again. + +Checking the time stamp allows you to edit the definition of a function +while Octave is running, and automatically use the new function +definition without having to restart your Octave session. Checking the +time stamp every time a function is used is rather inefficient, but it +has to be done to ensure that the correct function definition is used. + +Octave assumes that function files in the +@file{/usr/local/lib/octave/@value{VERSION}/m} directory tree will not +change, so it doesn't have to check their time stamps every time the +functions defined in those files are used. This is normally a very good +assumption and provides a significant improvement in performance for the +function files that are distributed with Octave. + +If you know that your own function files will not change while you are +running Octave, you can improve performance by setting the variable +@code{ignore_function_time_stamp} to @code{"all"}, so that Octave will +ignore the time stamps for all function files. Setting it to +@code{"system"} gives the default behavior. If you set it to anything +else, Octave will check the time stamps on all function files. + +@node Script Files, Dynamically Linked Functions, Function Files, Functions and Scripts +@section Script Files + +A script file is a file containing (almost) any sequence of Octave +commands. It is read and evaluated just as if you had typed each +command at the Octave prompt, and provides a convenient way to perform a +sequence of commands that do not logically belong inside a function. + +Unlike a function file, a script file must @emph{not} begin with the +keyword @code{function}. If it does, Octave will assume that it is a +function file, and that it defines a single function that should be +evaluated as soon as it is defined. + +A script file also differs from a function file in that the variables +named in a script file are not local variables, but are in the same +scope as the other variables that are visible on the command line. + +Even though a script file may not begin with the @code{function} +keyword, it is possible to define more than one function in a single +script file and load (but not execute) all of them at once. To do +this, the first token in the file (ignoring comments and other white +space) must be something other than @code{function}. If you have no +other statements to evaluate, you can use a statement that has no +effect, like this: + +@example +@group +# Prevent Octave from thinking that this +# is a function file: + +1; + +# Define function one: + +function one () + ... +@end group +@end example + +To have Octave read and compile these functions into an internal form, +you need to make sure that the file is in Octave's @code{LOADPATH}, then +simply type the base name of the file that contains the commands. +(Octave uses the same rules to search for script files as it does to +search for function files.) + +If the first token in a file (ignoring comments) is @code{function}, +Octave will compile the function and try to execute it, printing a +message warning about any non-whitespace characters that appear after +the function definition. + +Note that Octave does not try to lookup the definition of any identifier +until it needs to evaluate it. This means that Octave will compile the +following statements if they appear in a script file, or are typed at +the command line, + +@example +@group +# not a function file: +1; +function foo () + do_something (); +endfunction +function do_something () + do_something_else (); +endfunction +@end group +@end example + +@noindent +even though the function @code{do_something} is not defined before it is +referenced in the function @code{foo}. This is not an error because the +Octave does not need to resolve all symbols that are referenced by a +function until the function is actually evaluated. + +Since Octave doesn't look for definitions until they are needed, the +following code will always print @samp{bar = 3} whether it is typed +directly on the command line, read from a script file, or is part of a +function body, even if there is a function or script file called +@file{bar.m} in Octave's @code{LOADPATH}. + +@example +@group +eval ("bar = 3"); +bar +@end group +@end example + +Code like this appearing within a function body could fool Octave if +definitions were resolved as the function was being compiled. It would +be virtually impossible to make Octave clever enough to evaluate this +code in a consistent fashion. The parser would have to be able to +perform the @samp{eval ()} statement at compile time, and that would be +impossible unless all the references in the string to be evaluated could +also be resolved, and requiring that would be too restrictive (the +string might come from user input, or depend on things that are not +known until the function is evaluated). + +@node Dynamically Linked Functions, Organization of Functions, Script Files, Functions and Scripts +@section Dynamically Linked Functions + +On some systems, Octave can dynamically load and execute functions +written in C++ or other compiled languages. This currently only works +on systems that have a working version of the GNU dynamic linker, +@code{dld}. Unfortunately, @code{dld} does not work on very many +systems, but someone is working on making @code{dld} use the GNU Binary +File Descriptor library, @code{BFD}, so that may soon change. In any +case, it should not be too hard to make Octave's dynamic linking +features work on other systems using system-specific dynamic linking +facilities. + +Here is an example of how to write a C++ function that Octave can load. + +@example +#include <iostream.h> + +#include "defun-dld.h" +#include "tree-const.h" + +DEFUN_DLD ("hello", Fhello, Shello, -1, -1, + "hello (...)\n\ +\n\ +Print greeting followed by the values of all the arguments passed.\n\ +Returns all the arguments passed.") +@{ + Octave_object retval; + cerr << "Hello, world!\n"; + int nargin = args.length (); + for (int i = 1; i < nargin; i++) + retval (nargin-i-1) = args(i).eval (1); + return retval; +@} +@end example + +Octave's dynamic linking features currently have the following +limitations. + +@itemize @bullet +@item +Dynamic linking only works on systems that support the GNU dynamic +linker, @code{dld}. +@item +Clearing dynamically linked functions doesn't work. + +@item +Configuring Octave with @code{--enable-lite-kernel} seems to mostly work +to make nonessential built-in functions dynamically loaded, but there +also seem to be some problems. For example, fsolve seems to always +return @code{info == 3}. This is difficult to debug since @code{gdb} +won't seem to allow breakpoints to be set inside dynamically loaded +functions. + +@item +Octave uses a lot of memory if the dynamically linked functions are +compiled to include debugging symbols. This appears to be a limitation +with @code{dld}, and can be avoided by not using @code{-g} to compile +functions that will be linked dynamically. +@end itemize + +If you would like to volunteer to help improve Octave's ability to +dynamically link externally compiled functions, please contact +@code{bug-octave@@bevo.che.wisc.edu}. + +@node Organization of Functions, , Dynamically Linked Functions, Functions and Scripts +@section Organization of Functions Distributed with Octave + +Many of Octave's standard functions are distributed as function files. +They are loosely organized by topic, in subdirectories of +@file{OCTAVE_HOME/lib/octave/VERSION/m}, to make it easier to find +them. + +The following is a list of all the function file subdirectories, and the +types of functions you will find there. + +@table @file +@item control +Functions for design and simulation of automatic control systems. + +@item elfun +Elementary functions. + +@item general +Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90}, +and @code{triu}, as well as other basic functions, like +@code{is_matrix}, @code{nargchk}, etc. + +@item image +Image processing tools. These functions require the X Window System. + +@item linear-algebra +Functions for linear algebra. + +@item miscellaneous +Functions that don't really belong anywhere else. + +@item plot +A set of functions that implement the @sc{Matlab}-like plotting functions. + +@item polynomial +Functions for manipulating polynomials. + +@item set +Functions for creating and manipulating sets of unique values. + +@item signal +Functions for signal processing applications. + +@item specfun +Special functions. + +@item special-matrix +Functions that create special matrix forms. + +@item startup +Octave's system-wide startup file. + +@item statistics +Statistical functions. + +@item strings +Miscellaneous string-handling functions. +@end table + +@xref{User Preferences} for an explanation of the built-in variable +@code{LOADPATH}, and @ref{Function Files} for a description of the way +Octave resolves undefined variable and function names. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/gnuinfo.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,1130 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@c This file is meant to be included in any arbitrary piece of +@c documentation that wishes to describe the info program. Some day +@c info-stnd.texi should probably use this file instead of duplicating +@c its contents. +@c +@c This file documents the use of the standalone GNU Info program, +@c versions 2.7 and later. + +@node Using Info, Concept Index, Command Line Editing, Top +@appendix Using Info + +@menu +* Cursor Commands:: +* Scrolling Commands:: +* Node Commands:: +* Searching Commands:: +* Xref Commands:: +* Window Commands:: +* Printing Nodes:: +* Other Info Commands:: +* Info Variables:: +@end menu + +@dfn{Info} is a program which is used to view info files on an ASCII +terminal. @dfn{info files} are the result of processing texinfo files +with the program @code{makeinfo} or with the Emacs command @code{M-x +texinfo-format-buffer}. Finally, @dfn{texinfo} is a documentation +language which allows a printed manual and on-line documentation (an +info file) to be produced from a single source file. + +@menu +* Cursor Commands:: Commands which move the cursor within a node. +* Scrolling Commands:: Commands for moving the node around in a window. +* Node Commands:: Commands for selecting a new node. +* Searching Commands:: Commands for searching an info file. +* Xref Commands:: Commands for selecting cross references. +* Window Commands:: Commands which manipulate multiple windows. +* Printing Nodes:: How to print out the contents of a node. +* Other Info Commands:: A few commands that defy categories. +* Info Variables:: How to change the default behavior of Info. +@end menu + +@node Cursor Commands, Scrolling Commands, Using Info, Using Info +@appendixsec Moving the Cursor +@cindex cursor, moving +Many people find that reading screens of text page by page is made +easier when one is able to indicate particular pieces of text with some +kind of pointing device. Since this is the case, GNU Info (both the +Emacs and standalone versions) have several commands which allow you to +move the cursor about the screen. The notation used in this manual to +describe keystrokes is identical to the notation used within the Emacs +manual, and the GNU Readline manual. @xref{Characters, , Character +Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with +the notation. + +The following table lists the basic cursor movement commands in Info. +Each entry consists of the key sequence you should type to execute the +cursor movement, the @code{M-x}@footnote{@code{M-x} is also a command; +it invokes @code{execute-extended-command}. @xref{M-x, , Executing an +extended command, emacs, the GNU Emacs Manual}, for more detailed +information.} command name (displayed in parentheses), and a short +description of what the command does. All of the cursor motion commands +can take an @dfn{numeric} argument (@pxref{Other Info Commands, +@code{universal-argument}}), to find out how to supply them. With a +numeric argument, the motion commands are simply executed that many +times; for example, a numeric argument of 4 given to @code{next-line} +causes the cursor to move down 4 lines. With a negative numeric +argument, the motion is reversed; an argument of -4 given to the +@code{next-line} command would cause the cursor to move @emph{up} 4 +lines. + +@table @asis +@item @code{C-n} (@code{next-line}) +@kindex C-n, in Info windows +@findex next-line +Moves the cursor down to the next line. + +@item @code{C-p} (@code{prev-line}) +@kindex C-p, in Info windows +@findex prev-line +Move the cursor up to the previous line. + +@item @code{C-a} (@code{beginning-of-line}) +@kindex C-a, in Info windows +@findex beginning-of-line +Move the cursor to the start of the current line. + +@item @code{C-e} (@code{end-of-line}) +@kindex C-e, in Info windows +@findex end-of-line +Moves the cursor to the end of the current line. + +@item @code{C-f} (@code{forward-char}) +@kindex C-f, in Info windows +@findex forward-char +Move the cursor forward a character. + +@item @code{C-b} (@code{backward-char}) +@kindex C-b, in Info windows +@findex backward-char +Move the cursor backward a character. + +@item @code{M-f} (@code{forward-word}) +@kindex M-f, in Info windows +@findex forward-word +Moves the cursor forward a word. + +@item @code{M-b} (@code{backward-word}) +@kindex M-b, in Info windows +@findex backward-word +Moves the cursor backward a word. + +@item @code{M-<} (@code{beginning-of-node}) +@itemx @code{b} +@kindex b, in Info windows +@kindex M-<, in Info windows +@findex beginning-of-node +Moves the cursor to the start of the current node. + +@item @code{M->} (@code{end-of-node}) +@kindex M->, in Info windows +@findex end-of-node +Moves the cursor to the end of the current node. + +@item @code{M-r} (@code{move-to-window-line}) +@kindex M-r, in Info windows +@findex move-to-window-line +Moves the cursor to a specific line of the window. Without a numeric +argument, @code{M-r} moves the cursor to the start of the line in the +center of the window. With a numeric argument of @var{n}, @code{M-r} +moves the cursor to the start of the @var{n}th line in the window. +@end table + +@node Scrolling Commands, Node Commands, Cursor Commands, Using Info +@appendixsec Moving Text Within a Window +@cindex scrolling, in Info windows + +Sometimes you are looking at a screenful of text, and only part of the +current paragraph you are reading is visible on the screen. The +commands detailed in this section are used to shift which part of the +current node is visible on the screen. + +@table @asis +@item @code{SPC} (@code{scroll-forward}) +@itemx @code{C-v} +@kindex SPC, in Info windows +@kindex C-v, in Info windows +@findex scroll-forward +Shift the text in this window up. That is, show more of the node which +is currently below the bottom of the window. With a numeric argument, +show that many more lines at the bottom of the window; a numeric +argument of 4 would shift all of the text in the window up 4 lines +(discarding the top 4 lines), and show you four new lines at the bottom +of the window. Without a numeric argument, @key{SPC} takes the bottom +two lines of the window and places them at the top of the window, +redisplaying almost a completely new screenful of lines. + +@item @code{DEL} (@code{scroll-backward}) +@itemx @code{M-v} +@kindex DEL, in Info windows +@kindex M-v, in Info windows +@findex scroll-backward +Shift the text in this window down. The inverse of +@code{scroll-forward}. + +@end table + +@cindex scrolling through node structure +The @code{scroll-forward} and @code{scroll-backward} commands can also +move forward and backward through the node structure of the file. If +you press @key{SPC} while viewing the end of a node, or @key{DEL} while +viewing the beginning of a node, what happens is controlled by the +variable @code{scroll-behaviour}. @xref{Info Variables, +@code{scroll-behaviour}}, for more information. + +@table @asis +@item @code{C-l} (@code{redraw-display}) +@kindex C-l, in Info windows +@findex redraw-display +Redraw the display from scratch, or shift the line containing the cursor +to a specified location. With no numeric argument, @samp{C-l} clears +the screen, and then redraws its entire contents. Given a numeric +argument of @var{n}, the line containing the cursor is shifted so that +it is on the @var{n}th line of the window. + +@item @code{C-x w} (@code{toggle-wrap}) +@kindex C-w, in Info windows +@findex toggle-wrap +Toggles the state of line wrapping in the current window. Normally, +lines which are longer than the screen width @dfn{wrap}, i.e., they are +continued on the next line. Lines which wrap have a @samp{\} appearing +in the rightmost column of the screen. You can cause such lines to be +terminated at the rightmost column by changing the state of line +wrapping in the window with @code{C-x w}. When a line which needs more +space than one screen width to display is displayed, a @samp{$} appears +in the rightmost column of the screen, and the remainder of the line is +invisible. +@end table + +@node Node Commands, Searching Commands, Scrolling Commands, Using Info +@appendixsec Selecting a New Node +@cindex nodes, selection of in Info windows + +This section details the numerous Info commands which select a new node +to view in the current window. + +The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and +@samp{l}. + +When you are viewing a node, the top line of the node contains some Info +@dfn{pointers} which describe where the next, previous, and up nodes +are. Info uses this line to move about the node structure of the file +when you use the following commands: + +@table @asis +@item @code{n} (@code{next-node}) +@kindex n, in Info windows +@findex next-node +Selects the `Next' node. + +@item @code{p} (@code{prev-node}) +@kindex p, in Info windows +@findex prev-node +Selects the `Prev' node. + +@item @code{u} (@code{up-node}) +@kindex u, in Info windows +@findex up-node +Selects the `Up' node. +@end table + +You can easily select a node that you have already viewed in this window +by using the @samp{l} command -- this name stands for "last", and +actually moves through the list of already visited nodes for this +window. @samp{l} with a negative numeric argument moves forward through +the history of nodes for this window, so you can quickly step between +two adjacent (in viewing history) nodes. + +@table @asis +@item @code{l} (@code{history-node}) +@kindex l, in Info windows +@findex history-node +Selects the most recently selected node in this window. +@end table + +Two additional commands make it easy to select the most commonly +selected nodes; they are @samp{t} and @samp{d}. + +@table @asis +@item @code{t} (@code{top-node}) +@kindex t, in Info windows +@findex top-node +Selects the node @samp{Top} in the current info file. + +@item @code{d} (@code{dir-node}) +@kindex d, in Info windows +@findex dir-node +Selects the directory node (i.e., the node @samp{(dir)}). +@end table + +Here are some other commands which immediately result in the selection +of a different node in the current window: + +@table @asis +@item @code{<} (@code{first-node}) +@kindex <, in Info windows +@findex first-node +Selects the first node which appears in this file. This node is most +often @samp{Top}, but it doesn't have to be. + +@item @code{>} (@code{last-node}) +@kindex >, in Info windows +@findex last-node +Selects the last node which appears in this file. + +@item @code{]} (@code{global-next-node}) +@kindex ], in Info windows +@findex global-next-node +Moves forward or down through node structure. If the node that you are +currently viewing has a @samp{Next} pointer, that node is selected. +Otherwise, if this node has a menu, the first menu item is selected. If +there is no @samp{Next} and no menu, the same process is tried with the +@samp{Up} node of this node. + +@item @code{[} (@code{global-prev-node}) +@kindex [, in Info windows +@findex global-prev-node +Moves backward or up through node structure. If the node that you are +currently viewing has a @samp{Prev} pointer, that node is selected. +Otherwise, if the node has an @samp{Up} pointer, that node is selected, +and if it has a menu, the last item in the menu is selected. +@end table + +You can get the same behavior as @code{global-next-node} and +@code{global-prev-node} while simply scrolling through the file with +@key{SPC} and @key{DEL}; @xref{Info Variables, @code{scroll-behaviour}}, +for more information. + +@table @asis +@item @code{g} (@code{goto-node}) +@kindex g, in Info windows +@findex goto-node +Reads the name of a node and selects it. No completion is done while +reading the node name, since the desired node may reside in a separate +file. The node must be typed exactly as it appears in the info file. A +file name may be included as with any node specification, for example + +@example +@code{g(emacs)Buffers} +@end example + +finds the node @samp{Buffers} in the info file @file{emacs}. + +@item @code{C-x k} (@code{kill-node}) +@kindex C-x k, in Info windows +@findex kill-node +Kills a node. The node name is prompted for in the echo area, with a +default of the current node. @dfn{Killing} a node means that Info tries +hard to forget about it, removing it from the list of history nodes kept +for the window where that node is found. Another node is selected in +the window which contained the killed node. + +@item @code{C-x C-f} (@code{view-file}) +@kindex C-x C-f, in Info windows +@findex view-file +Reads the name of a file and selects the entire file. The command +@example +@code{C-x C-f @var{filename}} +@end example +is equivalent to typing +@example +@code{g(@var{filename})*} +@end example + +@item @code{C-x C-b} (@code{list-visited-nodes}) +@kindex C-x C-b, in Info windows +@findex list-visited-nodes +Makes a window containing a menu of all of the currently visited nodes. +This window becomes the selected window, and you may use the standard +Info commands within it. + +@item @code{C-x b} (@code{select-visited-node}) +@kindex C-x b, in Info windows +@findex select-visited-node +Selects a node which has been previously visited in a visible window. +This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is +created. +@end table + +@node Searching Commands, Xref Commands, Node Commands, Using Info +@appendixsec Searching an Info File +@cindex searching + +GNU Info allows you to search for a sequence of characters throughout an +entire info file, search through the indices of an info file, or find +areas within an info file which discuss a particular topic. + +@table @asis +@item @code{s} (@code{search}) +@kindex s, in Info windows +@findex search +Reads a string in the echo area and searches for it. + +@item @code{C-s} (@code{isearch-forward}) +@kindex C-s, in Info windows +@findex isearch-forward +Interactively searches forward through the info file for a string as you +type it. + +@item @code{C-r} (@code{isearch-backward}) +@kindex C-r, in Info windows +@findex isearch-backward +Interactively searches backward through the info file for a string as +you type it. + +@item @code{i} (@code{index-search}) +@kindex i, in Info windows +@findex index-search +Looks up a string in the indices for this info file, and selects a node +where the found index entry points to. + +@item @code{,} (@code{next-index-match}) +@kindex , in Info windows +@findex next-index-match +Moves to the node containing the next matching index item from the last +@samp{i} command. +@end table + +The most basic searching command is @samp{s} (@code{search}). The +@samp{s} command prompts you for a string in the echo area, and then +searches the remainder of the info file for an occurrence of that string. +If the string is found, the node containing it is selected, and the +cursor is left positioned at the start of the found string. Subsequent +@samp{s} commands show you the default search string within @samp{[} and +@samp{]}; pressing @key{RET} instead of typing a new string will use the +default search string. + +@dfn{Incremental searching} is similar to basic searching, but the +string is looked up while you are typing it, instead of waiting until +the entire search string has been specified. + +@node Xref Commands, Window Commands, Searching Commands, Using Info +@appendixsec Selecting Cross References + +We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up} +pointers which appear at the top of a node. In addition to these +pointers, a node may contain other pointers which refer you to a +different node, perhaps in another info file. Such pointers are called +@dfn{cross references}, or @dfn{xrefs} for short. + +@menu +* Parts of an Xref:: What a cross reference is made of. +* Selecting Xrefs:: Commands for selecting menu or note items. +@end menu + +@node Parts of an Xref, Selecting Xrefs, Xref Commands, Xref Commands +@appendixsubsec Parts of an Xref + +Cross references have two major parts: the first part is called the +@dfn{label}; it is the name that you can use to refer to the cross +reference, and the second is the @dfn{target}; it is the full name of +the node that the cross reference points to. + +The target is separated from the label by a colon @samp{:}; first the +label appears, and then the target. For example, in the sample menu +cross reference below, the single colon separates the label from the +target. + +@example +* Foo Label: Foo Target. More information about Foo. +@end example + +Note the @samp{.} which ends the name of the target. The @samp{.} is +not part of the target; it serves only to let Info know where the target +name ends. + +A shorthand way of specifying references allows two adjacent colons to +stand for a target name which is the same as the label name: + +@example +* Foo Commands:: Commands pertaining to Foo. +@end example + +In the above example, the name of the target is the same as the name of +the label, in this case @code{Foo Commands}. + +You will normally see two types of cross references while viewing nodes: +@dfn{menu} references, and @dfn{note} references. Menu references +appear within a node's menu; they begin with a @samp{*} at the beginning +of a line, and continue with a label, a target, and a comment which +describes what the contents of the node pointed to contains. + +Note references appear within the body of the node text; they begin with +@code{*Note}, and continue with a label and a target. + +Like @samp{Next}, @samp{Prev} and @samp{Up} pointers, cross references +can point to any valid node. They are used to refer you to a place +where more detailed information can be found on a particular subject. +Here is a cross reference which points to a node within the Texinfo +documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo +Manual}, for more information on creating your own texinfo cross +references. + +@node Selecting Xrefs, , Parts of an Xref, Xref Commands +@appendixsubsec Selecting Xrefs + +The following table lists the Info commands which operate on menu items. + +@table @asis +@item @code{1} (@code{menu-digit}) +@itemx @code{2} @dots{} @code{9} +@cindex 1 @dots{} 9, in Info windows +@kindex 1 @dots{} 9, in Info windows +@findex menu-digit +Within an Info window, pressing a single digit, (such as @samp{1}), +selects that menu item, and places its node in the current window. +For convenience, there is one exception; pressing @samp{0} selects the +@emph{last} item in the node's menu. + +@item @code{0} (@code{last-menu-item}) +@kindex 0, in Info windows +@findex last-menu-item +Select the last item in the current node's menu. + +@item @code{m} (@code{menu-item}) +@kindex m, in Info windows +@findex menu-item +Reads the name of a menu item in the echo area and selects its node. +Completion is available while reading the menu label. + +@item @code{M-x find-menu} +@findex find-menu +Moves the cursor to the start of this node's menu. +@end table + +This table lists the Info commands which operate on note cross references. + +@table @asis +@item @code{f} (@code{xref-item}) +@itemx @code{r} +@kindex f, in Info windows +@kindex r, in Info windows +@findex xref-item +Reads the name of a note cross reference in the echo area and selects +its node. Completion is available while reading the cross reference +label. +@end table + +Finally, the next few commands operate on menu or note references alike: + +@table @asis +@item @code{TAB} (@code{move-to-next-xref}) +@kindex TAB, in Info windows +@findex move-to-next-xref +Moves the cursor to the start of the next nearest menu item or note +reference in this node. You can then use @key{RET} +(@code{select-reference-this-line} to select the menu or note reference. + +@item @code{M-TAB} (@code{move-to-prev-xref}) +@kindex M-TAB, in Info windows +@findex move-to-prev-xref +Moves the cursor the start of the nearest previous menu item or note +reference in this node. + +@item @code{RET} (@code{select-reference-this-line}) +@kindex RET, in Info windows +@findex select-reference-this-line +Selects the menu item or note reference appearing on this line. +@end table + +@node Window Commands, Printing Nodes, Xref Commands, Using Info +@appendixsec Manipulating Multiple Windows +@cindex windows, manipulating + +A @dfn{window} is a place to show the text of a node. Windows have a +view area where the text of the node is displayed, and an associated +@dfn{mode line}, which briefly describes the node being viewed. + +GNU Info supports multiple windows appearing in a single screen; each +window is separated from the next by its modeline. At any time, there +is only one @dfn{active} window, that is, the window in which the cursor +appears. There are commands available for creating windows, changing +the size of windows, selecting which window is active, and for deleting +windows. + +@menu +* The Mode Line:: What appears in the mode line? +* Basic Windows:: Manipulating windows in Info. +* The Echo Area:: Used for displaying errors and reading input. +@end menu + +@node The Mode Line, Basic Windows, Window Commands, Window Commands +@appendixsubsec The Mode Line + +A @dfn{mode line} is a line of inverse video which appears at the bottom +of an info window. It describes the contents of the window just above +it; this information includes the name of the file and node appearing in +that window, the number of screen lines it takes to display the node, +and the percentage of text that is above the top of the window. It can +also tell you if the indirect tags table for this info file needs to be +updated, and whether or not the info file was compressed when stored on +disk. + +Here is a sample mode line for a window containing an uncompressed file +named @file{dir}, showing the node @samp{Top}. + +@example +-----Info: (dir)Top, 40 lines --Top--------------------------------------- + ^^ ^ ^^^ ^^ + (file)Node #lines where +@end example + +When a node comes from a file which is compressed on disk, this is +indicated in the mode line with two small @samp{z}'s. In addition, if +the info file containing the node has been split into subfiles, the name +of the subfile containing the node appears in the modeline as well: + +@example +--zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z--------------- +@end example + +When Info makes a node internally, such that there is no corresponding +info file on disk, the name of the node is surrounded by asterisks +(@samp{*}). The name itself tells you what the contents of the window +are; the sample mode line below shows an internally constructed node +showing possible completions: + +@example +-----Info: *Completions*, 7 lines --All----------------------------------- +@end example + +@node Basic Windows, The Echo Area, The Mode Line, Window Commands +@appendixsubsec Window Commands + +It can be convenient to view more than one node at a time. To allow +this, Info can display more than one @dfn{window}. Each window has its +own mode line (@pxref{The Mode Line}) and history of nodes viewed in that +window (@pxref{Node Commands, , @code{history-node}}). + +@table @asis +@item @code{C-x o} (@code{next-window}) +@cindex windows, selecting +@kindex C-x o, in Info windows +@findex next-window +Selects the next window on the screen. Note that the echo area can only be +selected if it is already in use, and you have left it temporarily. +Normally, @samp{C-x o} simply moves the cursor into the next window on +the screen, or if you are already within the last window, into the first +window on the screen. Given a numeric argument, @samp{C-x o} moves over +that many windows. A negative argument causes @samp{C-x o} to select +the previous window on the screen. + +@item @code{M-x prev-window} +@findex prev-window +Selects the previous window on the screen. This is identical to +@samp{C-x o} with a negative argument. + +@item @code{C-x 2} (@code{split-window}) +@cindex windows, creating +@kindex C-x 2, in Info windows +@findex split-window +Splits the current window into two windows, both showing the same node. +Each window is one half the size of the original window, and the cursor +remains in the original window. The variable @code{automatic-tiling} +can cause all of the windows on the screen to be resized for you +automatically, please @pxref{Info Variables, , automatic-tiling} for +more information. + +@item @code{C-x 0} (@code{delete-window}) +@cindex windows, deleting +@kindex C-x 0, in Info windows +@findex delete-window +Deletes the current window from the screen. If you have made too many +windows and your screen appears cluttered, this is the way to get rid of +some of them. + +@item @code{C-x 1} (@code{keep-one-window}) +@kindex C-x 1, in Info windows +@findex keep-one-window +Deletes all of the windows excepting the current one. + +@item @code{ESC C-v} (@code{scroll-other-window}) +@kindex ESC C-v, in Info windows +@findex scroll-other-window +Scrolls the other window, in the same fashion that @samp{C-v} might +scroll the current window. Given a negative argument, the "other" +window is scrolled backward. + +@item @code{C-x ^} (@code{grow-window}) +@kindex C-x ^, in Info windows +@findex grow-window +Grows (or shrinks) the current window. Given a numeric argument, grows +the current window that many lines; with a negative numeric argument, +the window is shrunk instead. + +@item @code{C-x t} (@code{tile-windows}) +@cindex tiling +@kindex C-x t, in Info windows +@findex tile-windows +Divides the available screen space among all of the visible windows. +Each window is given an equal portion of the screen in which to display +its contents. The variable @code{automatic-tiling} can cause +@code{tile-windows} to be called when a window is created or deleted. +@xref{Info Variables, , @code{automatic-tiling}}. +@end table + +@node The Echo Area, , Basic Windows, Window Commands +@appendixsubsec The Echo Area +@cindex echo area + +The @dfn{echo area} is a one line window which appears at the bottom of +the screen. It is used to display informative or error messages, and to +read lines of input from you when that is necessary. Almost all of the +commands available in the echo area are identical to their Emacs +counterparts, so please refer to that documentation for greater depth of +discussion on the concepts of editing a line of text. The following +table briefly lists the commands that are available while input is being +read in the echo area: + +@table @asis +@item @code{C-f} (@code{echo-area-forward}) +@kindex C-f, in the Info echo area +@findex echo-area-forward +Moves forward a character. + +@item @code{C-b} (@code{echo-area-backward}) +@kindex C-b, in the Info echo area +@findex echo-area-backward +Moves backward a character. + +@item @code{C-a} (@code{echo-area-beg-of-line}) +@kindex C-a, in the Info echo area +@findex echo-area-beg-of-line +Moves to the start of the input line. + +@item @code{C-e} (@code{echo-area-end-of-line}) +@kindex C-e, in the Info echo area +@findex echo-area-end-of-line +Moves to the end of the input line. + +@item @code{M-f} (@code{echo-area-forward-word}) +@kindex M-f, in the Info echo area +@findex echo-area-forward-word +Moves forward a word. + +@item @code{M-b} (@code{echo-area-backward-word}) +@kindex M-b, in the Info echo area +@findex echo-area-backward-word +Moves backward a word. + +@item @code{C-d} (@code{echo-area-delete}) +@kindex C-d, in the Info echo area +@findex echo-area-delete +Deletes the character under the cursor. + +@item @code{DEL} (@code{echo-area-rubout}) +@kindex DEL, in the Info echo area +@findex echo-area-rubout +Deletes the character behind the cursor. + +@item @code{C-g} (@code{echo-area-abort}) +@kindex C-g, in the Info echo area +@findex echo-area-abort +Cancels or quits the current operation. If completion is being read, +@samp{C-g} discards the text of the input line which does not match any +completion. If the input line is empty, @samp{C-g} aborts the calling +function. + +@item @code{RET} (@code{echo-area-newline}) +@kindex RET, in the Info echo area +@findex echo-area-newline +Accepts (or forces completion of) the current input line. + +@item @code{C-q} (@code{echo-area-quoted-insert}) +@kindex C-q, in the Info echo area +@findex echo-area-quoted-insert +Inserts the next character verbatim. This is how you can insert control +characters into a search string, for example. + +@item @var{printing character} (@code{echo-area-insert}) +@kindex printing characters, in the Info echo area +@findex echo-area-insert +Inserts the character. + +@item @code{M-TAB} (@code{echo-area-tab-insert}) +@kindex M-TAB, in the Info echo area +@findex echo-area-tab-insert +Inserts a TAB character. + +@item @code{C-t} (@code{echo-area-transpose-chars}) +@kindex C-t, in the Info echo area +@findex echo-area-transpose-chars +Transposes the characters at the cursor. +@end table + +The next group of commands deal with @dfn{killing}, and @dfn{yanking} +text. For an in depth discussion of killing and yanking, +@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} + +@table @asis +@item @code{M-d} (@code{echo-area-kill-word}) +@kindex M-d, in the Info echo area +@findex echo-area-kill-word +Kills the word following the cursor. + +@item @code{M-DEL} (@code{echo-area-backward-kill-word}) +@kindex M-DEL, in the Info echo area +@findex echo-area-backward-kill-word +Kills the word preceding the cursor. + +@item @code{C-k} (@code{echo-area-kill-line}) +@kindex C-k, in the Info echo area +@findex echo-area-kill-line +Kills the text from the cursor to the end of the line. + +@item @code{C-x DEL} (@code{echo-area-backward-kill-line}) +@kindex C-x DEL, in the Info echo area +@findex echo-area-backward-kill-line +Kills the text from the cursor to the beginning of the line. + +@item @code{C-y} (@code{echo-area-yank}) +@kindex C-y, in the Info echo area +@findex echo-area-yank +Yanks back the contents of the last kill. + +@item @code{M-y} (@code{echo-area-yank-pop}) +@kindex M-y, in the Info echo area +@findex echo-area-yank-pop +Yanks back a previous kill, removing the last yanked text first. +@end table + +Sometimes when reading input in the echo area, the command that needed +input will only accept one of a list of several choices. The choices +represent the @dfn{possible completions}, and you must respond with one +of them. Since there are a limited number of responses you can make, +Info allows you to abbreviate what you type, only typing as much of the +response as is necessary to uniquely identify it. In addition, you can +request Info to fill in as much of the response as is possible; this +is called @dfn{completion}. + +The following commands are available when completing in the echo area: + +@table @asis +@item @code{TAB} (@code{echo-area-complete}) +@itemx @code{SPC} +@kindex TAB, in the Info echo area +@kindex SPC, in the Info echo area +@findex echo-area-complete +Inserts as much of a completion as is possible. + +@item @code{?} (@code{echo-area-possible-completions}) +@kindex ?, in the Info echo area +@findex echo-area-possible-completions +Displays a window containing a list of the possible completions of what +you have typed so far. For example, if the available choices are: +@example +bar +foliate +food +forget +@end example +and you have typed an @samp{f}, followed by @samp{?}, the possible +completions would contain: +@example +foliate +food +forget +@end example +i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC} +or @key{TAB} would result in @samp{fo} appearing in the echo area, since +all of the choices which begin with @samp{f} continue with @samp{o}. +Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} +appearing in the echo area, since that is the only choice which begins +with @samp{fol}. + +@item @code{ESC C-v} (@code{echo-area-scroll-completions-window}) +@kindex ESC C-v, in the Info echo area +@findex echo-area-scroll-completions-window +Scrolls the completions window, if that is visible, or the "other" +window if not. +@end table + +@node Printing Nodes, Other Info Commands, Window Commands, Using Info +@appendixsec Printing Out Nodes +@cindex printing + +You may wish to print out the contents of a node as a quick reference +document for later use. Info provides you with a command for doing +this. In general, we recommend that you use @TeX{} to format the +document and print sections of it, by running @code{tex} on the texinfo +source file. + +@table @asis +@item @code{M-x print-node} +@findex print-node +@cindex INFO_PRINT_COMMAND, environment variable +Pipes the contents of the current node through the command in the +environment variable @code{INFO_PRINT_COMMAND}. If the variable doesn't +exist, the node is simply piped to @code{lpr}. +@end table + +@node Other Info Commands, Info Variables, Printing Nodes, Using Info +@appendixsec Miscellaneous Info Commands + +GNU Info contains several commands which self-document GNU Info: + +@table @asis +@item @code{M-x describe-command} +@cindex functions, describing +@cindex commands, describing +@findex describe-command +Reads the name of an Info command in the echo area and then displays a +brief description of what that command does. + +@item @code{M-x describe-key} +@cindex keys, describing +@findex describe-key +Reads a key sequence in the echo area, and then displays the name and +documentation of the Info command that the key sequence invokes. + +@item @code{M-x describe-variable} +Reads the name of a variable in the echo area and then displays a brief +description of what the variable affects. + +@item @code{M-x where-is} +@findex where-is +Reads the name of an Info command in the echo area, and then displays +a key sequence which can be typed in order to invoke that command. + +@item @code{C-h} (@code{get-help-window}) +@itemx @code{?} +@kindex C-h, in Info windows +@kindex ?, in Info windows +@findex get-help-window +Creates (or moves into) the window displaying @code{*Help*}, and places +a node containing a quick reference card into it. This window displays +the most concise information about GNU Info available. + +@item @code{h} (@code{get-info-help-node}) +@kindex h, in Info windows +@findex get-info-help-node +Tries hard to visit the node @code{(info)Help}. The info file +@file{info.texi} distributed with GNU Info contains this node. Of +course, the file must first be processed with @code{makeinfo}, and then +placed into the location of your info directory. +@end table + +Here are the commands for creating a numeric argument: + +@table @asis +@item @code{C-u} (@code{universal-argument}) +@cindex numeric arguments +@kindex C-u, in Info windows +@findex universal-argument +Starts (or multiplies by 4) the current numeric argument. @samp{C-u} is +a good way to give a small numeric argument to cursor movement or +scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while +@samp{C-u C-u C-n} moves the cursor down 16 lines. + +@item @code{M-1} (@code{add-digit-to-numeric-arg}) +@itemx @code{M-2} @dots{} @code{M-9} +@kindex M-1 @dots{} M-9, in Info windows +@findex add-digit-to-numeric-arg +Adds the digit value of the invoking key to the current numeric +argument. Once Info is reading a numeric argument, you may just type +the digits of the argument, without the Meta prefix. For example, you +might give @samp{C-l} a numeric argument of 32 by typing: + +@example +@kbd{C-u 3 2 C-l} +@end example +or +@example +@kbd{M-3 2 C-l} +@end example +@end table + +@samp{C-g} is used to abort the reading of a multi-character key +sequence, to cancel lengthy operations (such as multi-file searches) and +to cancel reading input in the echo area. + +@table @asis +@item @code{C-g} (@code{abort-key}) +@cindex cancelling typeahead +@cindex cancelling the current operation +@kindex C-g, in Info windows +@findex abort-key +Cancels current operation. +@end table + +The @samp{q} command of Info simply quits running Info. + +@table @asis +@item @code{q} (@code{quit}) +@cindex quitting +@kindex q, in Info windows +@findex quit +Exits GNU Info. +@end table + +If the operating system tells GNU Info that the screen is 60 lines tall, +and it is actually only 40 lines tall, here is a way to tell Info that +the operating system is correct. + +@table @asis +@item @code{M-x set-screen-height} +@findex set-screen-height +@cindex screen, changing the height of +Reads a height value in the echo area and sets the height of the +displayed screen to that value. +@end table + +Finally, Info provides a convenient way to display footnotes which might +be associated with the current node that you are viewing: + +@table @asis +@item @code{ESC C-f} (@code{show-footnotes}) +@kindex ESC C-f, in Info windows +@findex show-footnotes +@cindex footnotes, displaying +Shows the footnotes (if any) associated with the current node in another +window. You can have Info automatically display the footnotes +associated with a node when the node is selected by setting the variable +@code{automatic-footnotes}. +@xref{Info Variables, , @code{automatic-footnotes}}. +@end table + +@node Info Variables, , Other Info Commands, Using Info +@appendixsec Manipulating Variables + +GNU Info contains several @dfn{variables} whose values are looked at by various +Info commands. You can change the values of these variables, and thus +change the behavior of Info to more closely match your environment and +info file reading manner. + +@table @asis +@item @code{M-x set-variable} +@cindex variables, setting +@findex set-variable +Reads the name of a variable, and the value for it, in the echo area and +then sets the variable to that value. Completion is available when +reading the variable name; often, completion is available when reading +the value to give to the variable, but that depends on the variable +itself. If a variable does @emph{not} supply multiple choices to +complete over, it expects a numeric value. + +@item @code{M-x describe-variable} +@cindex variables, describing +@findex describe-variable +Reads the name of a variable in the echo area and then displays a brief +description of what the variable affects. +@end table + +Here is a list of the variables that you can set in Info. + +@table @code +@item automatic-footnotes +@vindex automatic-footnotes +When set to @code{On}, footnotes appear and disappear automatically. +This variable is @code{On} by default. When a node is selected, a +window containing the footnotes which appear in that node is created, +and the footnotes are displayed within the new window. The window that +Info creates to contain the footnotes is called @samp{*Footnotes*}. If +a node is selected which contains no footnotes, and a @samp{*Footnotes*} +window is on the screen, the @samp{*Footnotes*} window is deleted. +Footnote windows created in this fashion are not automatically tiled so +that they can use as little of the display as is possible. + +@item automatic-tiling +@vindex automatic-tiling +When set to @code{On}, creating or deleting a window resizes other +windows. This variable is @code{Off} by default. Normally, typing +@samp{C-x 2} divides the current window into two equal parts. When +@code{automatic-tiling} is set to @code{On}, all of the windows are +resized automatically, keeping an equal number of lines visible in each +window. There are exceptions to the automatic tiling; specifically, the +windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not} +resized through automatic tiling; they remain their original size. + +@item visible-bell +@vindex visible-bell +When set to @code{On}, GNU Info attempts to flash the screen instead of +ringing the bell. This variable is @code{Off} by default. Of course, +Info can only flash the screen if the terminal allows it; in the case +that the terminal does not allow it, the setting of this variable has no +effect. However, you can make Info perform quietly by setting the +@code{errors-ring-bell} variable to @code{Off}. + +@item errors-ring-bell +@vindex errors-ring-bell +When set to @code{On}, errors cause the bell to ring. The default +setting of this variable is @code{On}. + +@item gc-compressed-files +@vindex gc-compressed-files +When set to @code{On}, Info garbage collects files which had to be +uncompressed. The default value of this variable is @code{Off}. +Whenever a node is visited in Info, the info file containing that node +is read into core, and Info reads information about the tags and nodes +contained in that file. Once the tags information is read by Info, it +is never forgotten. However, the actual text of the nodes does not need +to remain in core unless a particular info window needs it. For +non-compressed files, the text of the nodes does not remain in core when +it is no longer in use. But de-compressing a file can be a time +consuming operation, and so Info tries hard not to do it twice. +@code{gc-compressed-files} tells Info it is okay to garbage collect the +text of the nodes of a file which was compressed on disk. + +@item show-index-match +@vindex show-index-match +When set to @code{On}, the portion of the matched search string is +highlighted in the message which explains where the matched search +string was found. The default value of this variable is @code{On}. +When Info displays the location where an index match was found, +(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the +string that you had typed is highlighted by displaying it in the inverse +case from its surrounding characters. + +@item scroll-behaviour +@vindex scroll-behaviour +Controls what happens when forward scrolling is requested at the end of +a node, or when backward scrolling is requested at the beginning of a +node. The default value for this variable is @code{Continuous}. There +are three possible values for this variable: + +@table @code +@item Continuous +Tries to get the first item in this node's menu, or failing that, the +@samp{Next} node, or failing that, the @samp{Next} of the @samp{Up}. +This behavior is identical to using the @samp{]} +(@code{global-next-node}) and @samp{[} (@code{global-prev-node}) +commands. + +@item Next Only +Only tries to get the @samp{Next} node. + +@item Page Only +Simply gives up, changing nothing. If @code{scroll-behaviour} is +@code{Page Only}, no scrolling command can change the node that is being +viewed. +@end table + +@item scroll-step +@vindex scroll-step +The number of lines to scroll when the cursor moves out of the window. +Scrolling happens automatically if the cursor has moved out of the +visible portion of the node text when it is time to display. Usually +the scrolling is done so as to put the cursor on the center line of the +current window. However, if the variable @code{scroll-step} has a +nonzero value, Info attempts to scroll the node text by that many lines; +if that is enough to bring the cursor back into the window, that is what +is done. The default value of this variable is 0, thus placing the +cursor (and the text it is attached to) in the center of the window. +Setting this variable to 1 causes a kind of "smooth scrolling" which +some people prefer. + +@item ISO-Latin +@cindex ISO Latin characters +@vindex ISO-Latin +When set to @code{On}, Info accepts and displays ISO Latin characters. +By default, Info assumes an ASCII character set. @code{ISO-Latin} tells +Info that it is running in an environment where the European standard +character set is in use, and allows you to input such characters to +Info, as well as display them. +@end table +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/gpl.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,397 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@cindex warranty +@cindex copyright +@node Copying, Introduction, Preface, Top +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@example +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end example + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/help.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,36 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Help, Programming Utilities, Command History Functions, Top +@chapter Help + +@findex help + +Octave's @code{help} command can be used to print brief usage-style +messages, or to display information directly from an on-line version of +the printed manual, using the GNU Info browser. If invoked without any +arguments, @code{help} prints a list of all the available operators, +functions, and built-in variables. If the first argument is @code{-i}, +the @code{help} command searches the index of the on-line version of +this manual for the given topics. + +For example, the command + +@example +help help +@end example + +@noindent +prints a short message describing the @code{help} command, and + +@example +help -i help +@end example + +@noindent +starts the GNU Info browser at this node in the on-line version of the +manual. + +@xref{Using Info}, for complete details about how to use the GNU Info +browser to read the on-line version of the manual.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/history.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,109 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Command History Functions, Help, System Utilities, Top +@chapter Command History Functions + +@findex edit_history +@findex run_history +@findex history + +Octave provides three functions for viewing, editing, and re-running +chunks of commands from the history list. + +The function @code{history} displays a list of commands that you have +executed. It also allows you to write the current history to a file for +safe keeping, and to replace the history list with the commands stored +in a named file. Valid arguments are: + +@table @code +@item -w file +Write the current history to the named file. If the name is omitted, +use the default history file (normally @file{~/.octave_hist}). + +@item -r file +Read the named file, replacing the current history list with its +contents. If the name is omitted, use the default history file +(normally @file{~/.octave_hist}). + +@item N +Only display the most recent @code{N} lines of history. + +@item -q +Don't number the displayed lines of history. This is useful for cutting +and pasting commands if you are using the X Window System. +@end table + +For example, to display the five most recent commands that you have +typed without displaying line numbers, use the command +@samp{history -q 5}. + +The function @code{edit_history} allows you to edit a block of commands +from the history list using the editor named by the environment +variable @code{EDITOR}, or the default editor (normally @code{vi}). It +is often more convenient to use @code{edit_history} to define functions +rather than attempting to enter them directly on the command line. +By default, the block of commands is executed as soon as you exit the +editor. To avoid executing any commands, simply delete all the lines +from the buffer before exiting the editor. + +The @code{edit_history} command takes two optional arguments specifying +the history numbers of first and last commands to edit. For example, +the command + +@example +edit_history 13 +@end example + +@noindent +extracts all the commands from the 13th through the last in the history +list. The command + +@example +edit_history 13 169 +@end example + +@noindent +only extracts commands 13 through 169. Specifying a larger number for +the first command than the last command reverses the list of commands +before placing them in the buffer to be edited. If both arguments are +omitted, the previous command in the history list is used. + +The command @code{run_history} is like @code{edit_history}, except that +the editor is not invoked, and the commands are simply executed as they +appear in the history list. + +@findex diary + +The @code{diary} command allows you to create a list of all commands +@emph{and} the output they produce, mixed together just as you see them +on your terminal. + +For example, the command + +@example +diary on +@end example + +@noindent +tells Octave to start recording your session in a file called +@file{diary} in your current working directory. To give Octave the name +of the file write to, use the a command like + +@example +diary my-diary.txt +@end example + +@noindent +Then Octave will write all of your commands to the file +@file{my-diary.txt}. + +To stop recording your session, use the command + +@example +diary off +@end example + +@noindent +Without any arguments, @code{diary} toggles the current diary state.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/hsuser.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,154 @@ +@ignore +This file documents the user interface to the GNU History library. + +Copyright (C) 1988, 1991 Free Software Foundation, Inc. +Authored by Brian Fox. + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@node Using History Interactively, Installation, Command Line Editing, Top +@chapter Using History Interactively + +This chapter describes how to use the GNU History Library interactively, +from a user's standpoint. +@c It should be considered a user's guide. For +@c information on using the GNU History Library in your own programs, +@c @pxref{Programming with GNU History}. + +@menu +* History Interaction:: What it feels like using History as a user. +@end menu + +@node History Interaction, , , Using History Interactively +@section History Interaction +@cindex expansion + +The History library provides a history expansion feature that is similar +to the history expansion in Csh. The following text describes the syntax +that you use to manipulate the history information. + +History expansion takes place in two parts. The first is to determine +which line from the previous history should be used during substitution. +The second is to select portions of that line for inclusion into the +current one. The line selected from the previous history is called the +@dfn{event}, and the portions of that line that are acted upon are +called @dfn{words}. The line is broken into words in the same fashion +that the Bash shell does, so that several English (or Unix) words +surrounded by quotes are considered as one word. + +@menu +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. +@end menu + +@node Event Designators, Word Designators, , History Interaction +@subsection Event Designators +@cindex event designators + +An event designator is a reference to a command line entry in the +history list. + +@table @asis + +@item @code{!} +Start a history substitution, except when followed by a space, tab, or +the end of the line... @key{=} or @key{(}. + +@item @code{!!} +Refer to the previous command. This is a synonym for @code{!-1}. + +@item @code{!n} +Refer to command line @var{n}. + +@item @code{!-n} +Refer to the command line @var{n} lines back. + +@item @code{!string} +Refer to the most recent command starting with @var{string}. + +@item @code{!?string}[@code{?}] +Refer to the most recent command containing @var{string}. + +@end table + +@node Word Designators, Modifiers, Event Designators, History Interaction +@subsection Word Designators + +A @key{:} separates the event specification from the word designator. It +can be omitted if the word designator begins with a @key{^}, @key{$}, +@key{*} or @key{%}. Words are numbered from the beginning of the line, +with the first word being denoted by a 0 (zero). + +@table @code + +@item 0 (zero) +The zero'th word. For many applications, this is the command word. + +@item n +The @var{n}'th word. + +@item ^ +The first argument. that is, word 1. + +@item $ +The last argument. + +@item % +The word matched by the most recent @code{?string?} search. + +@item x-y +A range of words; @code{-@var{y}} Abbreviates @code{0-@var{y}}. + +@item * +All of the words, excepting the zero'th. This is a synonym for @code{1-$}. +It is not an error to use @key{*} if there is just one word in the event. +The empty string is returned in that case. + +@end table + +@node Modifiers, , Word Designators, History Interaction +@subsection Modifiers + +After the optional word designator, you can add a sequence of one or more +of the following modifiers, each preceded by a @key{:}. + +@table @code + +@item # +The entire command line typed so far. This means the current command, +not the previous command, so it really isn't a word designator, and doesn't +belong in this section. + +@item h +Remove a trailing file name component, leaving only the head. + +@item r +Remove a trailing suffix of the form @samp{.}@var{suffix}, leaving the basename. + +@item e +Remove all but the suffix. + +@item t +Remove all leading file name components, leaving the tail. + +@item p +Print the new command but do not execute it. +@end table
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/image.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,131 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Image Processing, Audio Processing, Plotting, Top +@chapter Image Processing + +To display images using these functions, you must be using Octave with +the X Window System, and you must have either @code{xloadimage} or +@code{xv} installed. You do not need to be running X in order to +manipulate images, however, so some of these functions may be useful +even if you are not able to view the results. + +@ftable @code +@item colormap +Set the current colormap. + +@code{colormap (@var{map})} sets the current colormap to @var{map}. The +color map should be an @var{n} row by 3 column matrix. The columns +contain red, green, and blue intensities respectively. All entries +should be between 0 and 1 inclusive. The new colormap is returned. + +@code{colormap ("default")} restores the default colormap (a gray scale +colormap with 64 entries). The default colormap is returned. + +With no arguments, @code{colormap} returns the current color map. + +@item gray (@var{n}) +Create a gray colormap with values from 0 to @var{n}. The argument +@var{n} should be a scalar. If it is omitted, 64 is assumed. + +@item gray2ind +Convert a gray scale intensity image to an Octave indexed image. + +@item image +Display an Octave image matrix. + +@code{image (@var{x})} displays a matrix as a color image. The elements +of @var{x} are indices into the current colormap and should have values +between 1 and the length of the colormap. + +@code{image (@var{x}, @var{zoom})} changes the zoom factor. The default +value is 4. + +@item imagesc +Scale and display a matrix as an image. + +@code{imagesc (@var{x})} displays a scaled version of the matrix +@var{x}. The matrix is scaled so that its entries are indices into the +current colormap. The scaled matrix is returned. + +@code{imagesc (@var{x}, @var{zoom})} sets the magnification, the default +value is 4. + +@item imshow +Display images. + +@code{imshow (@var{x})} displays an indexed image using the current +colormap. + +@code{imshow (@var{x}, @var{map})} displays an indexed image using the +specified colormap. + +@code{imshow (@var{i}, @var{n})} displays a gray scale intensity image. + +@code{imshow (@var{r}, @var{g}, @var{b})} displays an RGB image. + +@item ind2gray +Convert an Octave indexed image to a gray scale intensity image. + +@code{@var{y} = ind2gray (@var{x})} converts an indexed image to a gray +scale intensity image. The current colormap is used to determine the +intensities. The intensity values lie between 0 and 1 inclusive. + +@code{@var{y} = ind2gray (@var{x}, @var{map})} uses the specified +colormap instead of the current one in the conversion process. + +@item ind2rgb +Convert an indexed image to red, green, and blue color components. + +@code{[@var{r}, @var{g}, @var{b}] = ind2rgb (@var{x})} uses the current +colormap for the conversion. + +@code{[@var{r}, @var{g}, @var{b}] = ind2rgb (@var{x}, @var{map})} uses +the specified colormap. + +@item loadimage +Load an image file. + +@code{[@var{x}, @var{map}] = loadimage (@var{file})} loads an image and +it's associated color map from the specified @var{file}. The image must +be stored in Octave's image format. + +@c @item rgb2ntsc +@c @item ntsc2rgb + +@item ocean (@var{n}) +Create color colormap. The argument @var{n} should be a scalar. If it +is omitted, 64 is assumed. + +@item rgb2ind +Convert and RGB image to an Octave indexed image. + +@code{[@var{x}, @var{map}] = rgb2ind (@var{r}, @var{g}, @var{b})} + +@item saveimage +Save a matrix to disk in image format. + +@code{saveimage (@var{file}, @var{x})} saves matrix @var{x} to @var{file} +in Octave's image format. The current colormap is also saved in the file. + +@code{saveimage (@var{file}, @var{x}, "img")} saves the image in the +default format and is the same as @code{saveimage (@var{file}, @var{x})}. + +@code{saveimage (@var{file}, @var{x}, "ppm")} saves the image in ppm +format instead of the default Octave image format. + +@code{saveimage (@var{file}, @var{x}, "ps")} saves the image in +PostScript format instead of the default Octave image format. (Note: +images saved in PostScript format can not be read back into Octave with +loadimage.) + +@code{saveimage (@var{file}, @var{x}, @var{fmt}, @var{map})} saves the +image along with the specified colormap in the specified format. + +Note: if the colormap contains only two entries and these entries are +black and white, the bitmap ppm and PostScript formats are used. If the +image is a gray scale image (the entries within each row of the colormap +are equal) the gray scale ppm and PostScript image formats are used, +otherwise the full color formats are used. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/in-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,8 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Info Index, , Readline Index, Top +@unnumbered Info Index + +@printindex in
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/install.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,500 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@c The text of this file will eventually appear in the file INSTALL +@c in the Octave distribution, as well as in the Octave manual. + +@ifclear INSTALLONLY +@node Installation, Trouble, Emacs, Top +@appendix Installing Octave +@end ifclear +@cindex installing Octave + +Here is the procedure for installing Octave from scratch on a Unix +system. For instructions on how to install the binary distributions of +Octave, see @ref{Binary Distributions}. + +@itemize @bullet +@item +Run the shell script @file{configure}. This will determine the features +your system has (or doesn't have) and create a file named Makefile from +each of the files named Makefile.in. + +Here is a summary of the configure options that are most frequently used +when building Octave: + +@table @code +@item --prefix=@var{prefix} +Install Octave in subdirectories below @var{prefix}. The default value +of @var{prefix} is @file{/usr/local}. + +@item --srcdir=@var{dir} +Look for Octave sources in the directory @var{dir}. + +@item --with-f2c +Use f2c even if Fortran compiler is available. + +@item --enable-dld +Use DLD to make Octave capable of dynamically linking +externally compiled functions. This only works on systems that have a +working port of DLD. + +@item --enable-lite-kernel +Compile smaller kernel. This currently requires DLD so that Octave can +load functions at run time that are not loaded at compile time. + +@item --help +Print a summary of the options recognized by the configure script. +@end table + +See the file INSTALL for more information about the command line options +used by configure. That file also contains instructions for compiling +in a directory other than where the source is located. + +@item +Run make. + +You will need a recent version of GNU make. Modifying Octave's +Makefiles to work with other make programs is probably not worth +your time. We recommend you get and compile GNU make instead. + +For plotting, you will need to have gnuplot installed on your system. +Gnuplot is a command-driven interactive function plotting program. +Gnuplot is copyrighted, but freely distributable. The `gnu' in gnuplot +is a coincidence---it is not related to the GNU project or the FSF in +any but the most peripheral sense. + +For version @value{VERSION}, you must have the GNU C++ compiler (gcc) +version 2.6.3 or later to compile Octave. You will also need version +2.6.1 of the GNU C++ class library (libg++). If you plan to modify the +parser you will also need GNU bison and fles. If you modify the +documentation, you will need GNU Texinfo, along with the patch for the +makeinfo program that is distributed with Octave. + +GNU make, gcc, and libg++, gnuplot, bison, flex, and Texinfo are all +available from many anonymous ftp archives. The primary site is +prep.ai.mit.edu, but it is often very busy. A list of sites that mirror +the software on prep is available by anonymous ftp from prep.ai.mit.edu +in the file /pub/gnu/GNUinfo/FTP, or by fingering fsf@@prep.ai.mit.edu. + +If you don't have a Fortran compiler, or if your Fortran compiler +doesn't work like the traditional Unix f77, you will need to have the +Fortran to C translator f2c. You can get f2c from any +number of anonymous ftp archives. The most recent version of f2c +is always available from netlib.att.com. + +On an otherwise idle SPARCstation II, it will take somewhere between 60 +and 90 minutes to compile everything, depending on whether you are +compiling the Fortran libraries with f2c or using the Fortran compiler +directly. You will need about 50 megabytes of disk storage to work with +(considerably less if you don't compile with debugging symbols). To do +that, use the command + +@example +make CFLAGS=-O CXXFLAGS=-O LDFLAGS= +@end example + +@noindent +instead of just @samp{make}. + +@item +If you encounter errors while compiling Octave, first check the list of +known problems below to see if there is a workaround or solution for +your problem. If not, +@ifclear INSTALLONLY +see @ref{Trouble}, +@end ifclear +@ifset INSTALLONLY +see the file BUGS +@end ifset +for information about how to report bugs. + +@item +Once you have successfully compiled Octave, run @samp{make install}. + +This will install a copy of octave, its libraries, and its documentation +in the destination directory. As distributed, Octave is installed in +the following directories: + +@table @file +@item @var{prefix}/bin +Octave and other binaries that people will want to run directly. + +@item @var{prefix}/lib +Libraries like libcruft.a and liboctave.a. + +@item @var{prefix}/include/octave +Include files distributed with Octave. + +@item @var{prefix}/man/man1 +Unix-style man pages describing Octave. + +@item @var{prefix}/info +Info files describing Octave. + +@item @var{prefix}/lib/octave/@var{version}/m +Function files distributed with Octave. This includes the Octave +version, so that multiple versions of Octave may be installed at the +same time. + +@item @var{prefix}/lib/octave/@var{version}/exec/@var{host_type} +Executables to be run by Octave rather than the user. + +@item @var{prefix}/lib/octave/@var{version}/oct/@var{host_type} +Object files that will be dynamically loaded. + +@item @var{prefix}/lib/octave/@var{version}/imagelib +Image files that are distributed with Octave. +@end table + +@noindent +where @var{prefix} defaults to @file{/usr/local}, @var{version} +stands for the current version number of the interpreter, and +@var{host_type} is the type of computer on which Octave is installed +(for example, @samp{i486-unknown-gnu}). +@end itemize + +@menu +* Installation Problems:: +* Binary Distributions:: +@end menu + +@node Installation Problems, Binary Distributions, Installation, Installation +@appendixsec Installation Problems + +This section contains a list of problems (and some apparent problems +that don't really mean anything is wrong) that may show up during +installation of Octave. + +@c XXX FIXME XXX --- this might be a good place to explain the terms for +@c FSQP and NPSOL. + +@itemize @bullet +@item +If @code{configure} fails when trying to create its output files, you +may have found a limitation in the version of @code{sed} on your +system. Using GNU @code{sed} avoids the problem. + +@item +You may need to edit some files in the gcc include subdirectory to add +prototypes for functions there. For example, Ultrix 4.2 needs proper +declarations for the @code{signal()} and the @code{SIG_IGN} macro in the +file @file{signal.h}. + +On some systems the @code{SIG_IGN} macro is defined to be something like +this: + +@example +#define SIG_IGN (void (*)())1 +@end example + +@noindent +when it should really be something like: + +@example +#define SIG_IGN (void (*)(int))1 +@end example + +@noindent +to match the prototype declaration for @code{signal()}. + +The gcc fixincludes/fixproto script should probably fix this when gcc +installs its modified set of header files, but I don't think that's +been done yet. + +@item +There is a bug with the makeinfo program that is distributed with +texinfo-3.1 that causes the indices in Octave's on-line manual to be +generated incorrectly. If you need to recreate the on-line +documentation, you should get the makeinfo program that is distributed +with texinfo-3.1 and apply the patch for makeinfo that is distributed +with Octave. See the file MAKEINFO.PATCH for more details. + +@item +If you don't have NPSOL but you still want to be able to solve NLPs, or +if you don't have QPSOL but you still want to solve QPs, you'll need to +find replacements or order them from Stanford. If you know of a freely +redistributable replacement, please let us know---we might be interested +in distributing it with Octave. + +You can get more information about NPSOL and QPSOL from + +@quotation +Stanford Business Sofrtware, Inc.@* +2680 Bayshore Parkway, Suite 304@* +Mountain View, CA 94043@* +Tel: (415) 962-8719@* +Fax: (415) 962-1869 +@end quotation + +Octave may soon support FSQP, an NLP solver from Andre Tits +(andre@@src.umd.edu) of the University of Maryland. FSQP is available +free of charge to academic sites, but can not be redistributed to third +parties. + +@item +Some of the Fortran subroutines may fail to compile with older versions +of the Sun Fortran compiler. If you get errors like + +@example +zgemm.f: + zgemm: +warning: unexpected parent of complex expression subtree +zgemm.f, line 245: warning: unexpected parent of complex expression subtree +warning: unexpected parent of complex expression subtree +zgemm.f, line 304: warning: unexpected parent of complex expression subtree +warning: unexpected parent of complex expression subtree +zgemm.f, line 327: warning: unexpected parent of complex expression subtree +pcc_binval: missing IR_CONV in complex op +make[2]: *** [zgemm.o] Error 1 +@end example + +@noindent +when compiling the Fortran subroutines in the @file{libcruft} +subdirectory, you should either upgrade your compiler or try compiling +with optimization turned off. + +@item +On NeXT systems, if you get errors like this: + +@example +/usr/tmp/cc007458.s:unknown:Undefined local symbol LBB7656 +/usr/tmp/cc007458.s:unknown:Undefined local symbol LBE7656 +@end example + +@noindent +when compiling @file{Array.cc} and @file{Matrix.cc}, try recompiling +these files without @code{-g}. + +@item +Some people have reported that calls to shell_cmd and the pager do not +work on SunOS systems. This is apparently due to having +@code{G_HAVE_SYS_WAIT} defined to be 0 instead of 1 when compiling +libg++. + +@item +On NeXT systems, linking to @file{libsys_s.a} may fail to resolve the +following functions + +@example +_tcgetattr +_tcsetattr +_tcflow +@end example + +@noindent +which are part of @file{libposix.a}. Unfortunately, linking Octave with +@code{-posix} results in the following undefined symbols. + +@example +.destructors_used +.constructors_used +_objc_msgSend +_NXGetDefaultValue +_NXRegisterDefaults +.objc_class_name_NXStringTable +.objc_class_name_NXBundle +@end example + +One kludge around this problem is to extract @file{termios.o} from +@file{libposix.a}, put it in Octave's @file{src} directory, and add it +to the list of files to link together in the Makefile. Suggestions for +better ways to solve this problem are welcome! + +@item +With g++ 2.6.3 (and possibly other 2.6.x versions) on some Intel x86 +systems, compiling @file{Array-d.cc} fails with the messages like + +@example +as: /tmp/cc005254.s:4057: Local symbol LBB103 never defined. +as: /tmp/cc005254.s:4057: Local symbol LBE103 never defined. +@end example + +@noindent +A possible workaround for this is to compile without @code{-g}. + +@item +If Octave crashes immediately with a floating point exception, it is +likely that it is failing to initialize the IEEE floating point values +for infinity and NaN. + +If your system actually does support IEEE arithmetic, you should be able +to fix this problem by modifying the function @code{octave_ieee_init} in +the file @file{sysdep.cc} to correctly initialize Octave's internal +infinity and NaN variables. + +If your system does not support IEEE arithmetic but Octave's configure +script incorrectly determined that it does, you can work around the +problem by editing the file @file{config.h} to not define +@code{HAVE_ISINF}, @code{HAVE_FINITE}, and @code{HAVE_ISNAN}. + +In any case, please report this as a bug since it might be possible to +modify Octave's configuration script to automatically determine the +proper thing to do. + +@item +Using the -O flag with old versions of the Sun Fortran compiler +apparently prevents if from compiling some of the Fortran subroutines +that Octave uses. The workaround is to not use -O for those +subroutines. + +@ignore +@c These next two items should no longer be problems, since g++ and +@c libg++ use a different method for installing an appropriate set of +@c header files. +@item +Problems with finite and isinf on systems that don't have @code{isinf()} +but do have @code{finite()}. + +The copy of @file{math.h} supplied with libg++ version 2.3 (and possibly +other versions as well) declares @code{finite()} as + +@example +double finite (double); +@end example + +@noindent +even though some (many? all?) systems declare it as + +@example +int finite (double); +@end example + +If the copy of @file{math.h} from libg++ was installed, you should edit +it so that the libg++ declaration of @samp{finite()} matches the +system's. + +@item +Problems compiling octave.cc on RS/6000 (and possibly other) +systems: + +If octave.cc fails to compile due to parse errors in system include +files and undeclared subroutines like `gethostname' and `endpwent', +it is probably because not all of the libg++ include files have been +installed. This appears to be a problem with libg++ version 2.3. +Here's a fix: + +Apply the following patch to @file{libg++/config/rs6000.mh} and re-run +make install for libg++. + +@example +*** rs6000.mh~ Mon Aug 17 19:18:44 1992 +--- rs6000.mh Mon Dec 28 23:54:57 1992 +*************** +*** 3,6 **** + # /usr/include/unistd.h has write(int, char*, unsigned) instead + # of write(int, const void*, size_t). This causes problems due + # to g++ new pedantic dis-allowal of void* -> char* conversions. +! G_CONFIG_ARGS = "HAVE_UNISTD=0 /*broken*/" +--- 3,12 ---- + # /usr/include/unistd.h has write(int, char*, unsigned) instead + # of write(int, const void*, size_t). This causes problems due + # to g++ new pedantic dis-allowal of void* -> char* conversions. +! G_CONFIG_ARGS = "HAVE_UNISTD=0 /*broken*/" +! +! # If the C include files are C++-ready (with extern "C"), +! # define: HAVE_CPLUS_EXTERN = 1 and: WRAP_C_INCLUDES = +! # If not, define HAVE_CPLUS_EXTERN = 0, and do not define +! # WRAP_C_INCLUDES here. +! HAVE_CPLUS_EXTERN = 0 +@end example +@end ignore +@end itemize + +@node Binary Distributions, , Installation Problems, Installation +@appendixsec Binary Distributions + +This section contains instructions for creating and installing a +binary distribution. + +@menu +* Installing Octave from a Binary Distribution:: +* Creating a Binary Distribution:: +@end menu + +@node Installing Octave from a Binary Distribution, Creating a Binary Distribution, Binary Distributions, Binary Distributions +@appendixsubsec Installing Octave from a Binary Distribution + +@itemize @bullet +@item +To install Octave from a binary distribution, execute the command + +@example +sh ./doinstall.sh +@end example + +@noindent +in the top level directory of the distribution. + +Binary distributions are normally compiled assuming that Octave will be +installed in the following subdirectories of @file{/usr/local}. + +@table @file +@item bin +Octave and other binaries that people will want to run directly. + +@item man/man1 +Unix-style man pages describing Octave. + +@item info +Info files describing Octave. + +@item lib/octave/@var{version}/m +Function files distributed with Octave. This includes the Octave +version, so that multiple versions of Octave may be installed at the +same time. + +@item lib/octave/@var{version}/exec/@var{host_type} +Executables to be run by Octave rather than the user. + +@ignore +@item lib/octave/@var{version}/oct/@var{host_type} +Object files that will be dynamically loaded. +@end ignore + +@item lib/octave/@var{version}/imagelib +Image files that are distributed with Octave. +@end table + +@noindent +where @var{version} stands for the current version number of the +interpreter, and @var{host_type} is the type of computer on which Octave +is installed (for example, @samp{i486-unknown-gnu}). + +If these directories don't exist, the script @file{doinstall.sh} will +create them for you. + +If this is possible for you to install Octave in @file{/usr/local}, or +if you would prefer to install it in a different directory, you can +specify the name of the top level directory as an argument to the +doinstall.sh script. For example: + +@example +sh ./doinstall.sh /some/other/directory +@end example + +@noindent +Octave will then be installed in subdirectories of the directory @file{/some/other/directory} +@end itemize + +@node Creating a Binary Distribution, , Installing Octave from a Binary Distribution, Binary Distributions +@appendixsubsec Creating a Binary Distribution + +Here is how to build a binary distribution for others. + +@itemize @bullet +@item +Build Octave in the same directory as the source. This is required +since the @samp{binary-dist} targets in the Makefiles will not work if +you compile outside the source tree. + +@item +Use @samp{CFLAGS=-O CXXFLAGS=-O LDFLAGS=} as arguments for Make because +most people who get the binary distributions are probably not going to +be interested in debugging Octave. + +@item +Type @samp{make binary-dist}. This will build everything and then pack +it up for distribution. +@end itemize
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/install1.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,22 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@setfilename INSTALL +@set INSTALLONLY + +@include conf.texi + +@c The immediately following lines apply to the INSTALL file +@c which is generated using this file. + +This file documents the installation of Octave. + +Octave is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation. + +@node Installation, Installation, Installation, (dir) +@chapter Installing Octave +@include install.texi +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/intro-fig.tex Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,594 @@ +% GNUPLOT: LaTeX picture with Postscript +\setlength{\unitlength}{0.1bp} +\special{! +%!PS-Adobe-2.0 +%%Creator: gnuplot +%%DocumentFonts: Helvetica +%%BoundingBox: 50 50 770 554 +%%Pages: (atend) +%%EndComments +/gnudict 40 dict def +gnudict begin +/Color false def +/Solid false def +/gnulinewidth 5.000 def +/vshift -33 def +/dl {10 mul} def +/hpt 31.5 def +/vpt 31.5 def +/M {moveto} bind def +/L {lineto} bind def +/R {rmoveto} bind def +/V {rlineto} bind def +/vpt2 vpt 2 mul def +/hpt2 hpt 2 mul def +/Lshow { currentpoint stroke M + 0 vshift R show } def +/Rshow { currentpoint stroke M + dup stringwidth pop neg vshift R show } def +/Cshow { currentpoint stroke M + dup stringwidth pop -2 div vshift R show } def +/DL { Color {setrgbcolor Solid {pop []} if 0 setdash } + {pop pop pop Solid {pop []} if 0 setdash} ifelse } def +/BL { stroke gnulinewidth 2 mul setlinewidth } def +/AL { stroke gnulinewidth 2 div setlinewidth } def +/PL { stroke gnulinewidth setlinewidth } def +/LTb { BL [] 0 0 0 DL } def +/LTa { AL [1 dl 2 dl] 0 setdash 0 0 0 setrgbcolor } def +/LT0 { PL [] 0 1 0 DL } def +/LT1 { PL [4 dl 2 dl] 0 0 1 DL } def +/LT2 { PL [2 dl 3 dl] 1 0 0 DL } def +/LT3 { PL [1 dl 1.5 dl] 1 0 1 DL } def +/LT4 { PL [5 dl 2 dl 1 dl 2 dl] 0 1 1 DL } def +/LT5 { PL [4 dl 3 dl 1 dl 3 dl] 1 1 0 DL } def +/LT6 { PL [2 dl 2 dl 2 dl 4 dl] 0 0 0 DL } def +/LT7 { PL [2 dl 2 dl 2 dl 2 dl 2 dl 4 dl] 1 0.3 0 DL } def +/LT8 { PL [2 dl 2 dl 2 dl 2 dl 2 dl 2 dl 2 dl 4 dl] 0.5 0.5 0.5 DL } def +/P { stroke [] 0 setdash + currentlinewidth 2 div sub M + 0 currentlinewidth V stroke } def +/D { stroke [] 0 setdash 2 copy vpt add M + hpt neg vpt neg V hpt vpt neg V + hpt vpt V hpt neg vpt V closepath stroke + P } def +/A { stroke [] 0 setdash vpt sub M 0 vpt2 V + currentpoint stroke M + hpt neg vpt neg R hpt2 0 V stroke + } def +/B { stroke [] 0 setdash 2 copy exch hpt sub exch vpt add M + 0 vpt2 neg V hpt2 0 V 0 vpt2 V + hpt2 neg 0 V closepath stroke + P } def +/C { stroke [] 0 setdash exch hpt sub exch vpt add M + hpt2 vpt2 neg V currentpoint stroke M + hpt2 neg 0 R hpt2 vpt2 V stroke } def +/T { stroke [] 0 setdash 2 copy vpt 1.12 mul add M + hpt neg vpt -1.62 mul V + hpt 2 mul 0 V + hpt neg vpt 1.62 mul V closepath stroke + P } def +/S { 2 copy A C} def +end +%%EndProlog +} +\begin{picture}(3600,2160)(0,0) +\special{" +%%Page: 1 1 +gnudict begin +gsave +50 50 translate +0.100 0.100 scale +0 setgray +/Helvetica findfont 100 scalefont setfont +newpath +-500.000000 -500.000000 translate +LTa +480 151 M +2937 0 V +480 151 M +0 1958 V +LTb +480 151 M +63 0 V +2874 0 R +-63 0 V +480 543 M +63 0 V +2874 0 R +-63 0 V +480 934 M +63 0 V +2874 0 R +-63 0 V +480 1326 M +63 0 V +2874 0 R +-63 0 V +480 1717 M +63 0 V +2874 0 R +-63 0 V +480 2109 M +63 0 V +2874 0 R +-63 0 V +480 151 M +0 63 V +0 1895 R +0 -63 V +774 151 M +0 63 V +0 1895 R +0 -63 V +1067 151 M +0 63 V +0 1895 R +0 -63 V +1361 151 M +0 63 V +0 1895 R +0 -63 V +1655 151 M +0 63 V +0 1895 R +0 -63 V +1949 151 M +0 63 V +0 1895 R +0 -63 V +2242 151 M +0 63 V +0 1895 R +0 -63 V +2536 151 M +0 63 V +0 1895 R +0 -63 V +2830 151 M +0 63 V +0 1895 R +0 -63 V +3123 151 M +0 63 V +0 1895 R +0 -63 V +3417 151 M +0 63 V +0 1895 R +0 -63 V +480 151 M +2937 0 V +0 1958 V +-2937 0 V +480 151 L +LT0 +3114 1946 M +180 0 V +480 934 M +495 556 L +510 361 L +14 -94 V +15 -46 V +15 -24 V +15 -13 V +14 -8 V +15 -5 V +15 -3 V +15 -2 V +14 -1 V +15 -1 V +15 -1 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 1 V +15 0 V +15 1 V +15 0 V +14 1 V +15 1 V +15 1 V +15 1 V +14 1 V +15 1 V +15 1 V +15 1 V +15 1 V +14 2 V +15 1 V +15 2 V +15 2 V +14 2 V +15 2 V +15 2 V +15 2 V +14 2 V +15 3 V +15 2 V +15 3 V +14 3 V +15 3 V +15 3 V +15 4 V +14 4 V +15 4 V +15 4 V +15 4 V +14 5 V +15 5 V +15 5 V +15 5 V +14 6 V +15 6 V +15 6 V +15 7 V +15 7 V +14 7 V +15 8 V +15 8 V +15 8 V +14 9 V +15 9 V +15 10 V +15 10 V +14 10 V +15 11 V +15 11 V +15 12 V +14 12 V +15 12 V +15 13 V +15 13 V +14 14 V +15 14 V +15 14 V +15 15 V +14 15 V +15 16 V +15 16 V +15 16 V +14 16 V +15 16 V +15 17 V +15 17 V +15 17 V +14 17 V +15 17 V +15 17 V +15 18 V +14 17 V +15 17 V +15 17 V +15 17 V +14 16 V +15 17 V +15 16 V +15 16 V +14 16 V +15 16 V +15 15 V +15 15 V +14 14 V +15 14 V +15 14 V +15 13 V +14 13 V +15 13 V +15 12 V +15 12 V +15 11 V +14 11 V +15 10 V +15 11 V +15 9 V +14 9 V +15 9 V +15 9 V +15 8 V +14 8 V +15 7 V +15 7 V +15 7 V +14 6 V +15 6 V +15 6 V +15 5 V +14 5 V +15 5 V +15 5 V +15 4 V +14 4 V +15 4 V +15 4 V +15 3 V +14 3 V +15 3 V +15 3 V +15 3 V +15 2 V +14 2 V +15 2 V +15 1 V +15 2 V +14 1 V +15 1 V +15 0 V +15 0 V +14 0 V +15 -1 V +15 -1 V +15 -2 V +14 -3 V +15 -3 V +15 -4 V +15 -6 V +14 -6 V +15 -8 V +15 -10 V +15 -11 V +14 -13 V +15 -15 V +15 -18 V +15 -21 V +14 -23 V +15 -25 V +15 -29 V +15 -31 V +15 -33 V +14 -35 V +15 -36 V +15 -37 V +15 -37 V +14 -37 V +15 -35 V +15 -34 V +15 -32 V +14 -29 V +15 -27 V +15 -24 V +15 -21 V +14 -19 V +15 -16 V +15 -14 V +15 -12 V +14 -9 V +15 -8 V +15 -6 V +15 -5 V +14 -4 V +15 -2 V +15 -1 V +15 1 V +14 1 V +15 2 V +15 3 V +LT1 +3114 1846 M +180 0 V +480 1717 M +15 34 V +15 -124 V +14 -186 V +15 -193 V +15 -178 V +569 915 L +583 784 L +598 674 L +15 -92 V +15 -76 V +14 -63 V +15 -52 V +15 -42 V +15 -36 V +14 -28 V +15 -24 V +15 -20 V +15 -16 V +14 -13 V +15 -11 V +15 -9 V +15 -7 V +14 -6 V +15 -5 V +15 -4 V +15 -3 V +14 -3 V +15 -2 V +15 -2 V +15 -2 V +15 -1 V +14 -1 V +15 -1 V +15 -1 V +15 0 V +14 -1 V +15 0 V +15 0 V +15 -1 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 -1 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 0 V +14 0 V +15 0 V +15 0 V +15 1 V +14 0 V +15 0 V +15 0 V +15 0 V +15 0 V +14 1 V +15 0 V +15 0 V +15 1 V +14 0 V +15 1 V +15 1 V +15 1 V +14 1 V +15 1 V +15 1 V +15 2 V +14 2 V +15 3 V +15 3 V +15 3 V +14 5 V +15 4 V +15 6 V +15 6 V +14 8 V +15 8 V +15 10 V +15 11 V +14 11 V +15 13 V +15 13 V +15 14 V +15 14 V +14 14 V +15 13 V +15 11 V +15 11 V +14 8 V +15 6 V +15 4 V +15 1 V +14 -1 V +15 -3 V +15 -5 V +15 -7 V +14 -7 V +15 -9 V +15 -9 V +15 -9 V +14 -10 V +15 -9 V +15 -10 V +15 -9 V +14 -8 V +15 -8 V +15 -8 V +15 -7 V +14 -6 V +15 -6 V +15 -6 V +stroke +grestore +end +showpage +} +\put(3054,1846){\makebox(0,0)[r]{line 2}} +\put(3054,1946){\makebox(0,0)[r]{line 1}} +\put(3417,51){\makebox(0,0){50}} +\put(3123,51){\makebox(0,0){45}} +\put(2830,51){\makebox(0,0){40}} +\put(2536,51){\makebox(0,0){35}} +\put(2242,51){\makebox(0,0){30}} +\put(1949,51){\makebox(0,0){25}} +\put(1655,51){\makebox(0,0){20}} +\put(1361,51){\makebox(0,0){15}} +\put(1067,51){\makebox(0,0){10}} +\put(774,51){\makebox(0,0){5}} +\put(480,51){\makebox(0,0){0}} +\put(420,2109){\makebox(0,0)[r]{2.5}} +\put(420,1717){\makebox(0,0)[r]{2}} +\put(420,1326){\makebox(0,0)[r]{1.5}} +\put(420,934){\makebox(0,0)[r]{1}} +\put(420,543){\makebox(0,0)[r]{0.5}} +\put(420,151){\makebox(0,0)[r]{0}} +\end{picture}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/intro.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,548 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Introduction, Invoking Octave, Copying, Top +@chapter A Brief Introduction to Octave +@cindex introduction + +This manual documents how to run, install and port Octave, and how +to report bugs. + +Octave is a high-level language, primarily intended for numerical +computations. It provides a convenient command line interface for +solving linear and nonlinear problems numerically, and for performing +other numerical experiments. It may also be used as a batch-oriented +language. + +This document corresponds to Octave version @value{VERSION}. + +@c XXX FIXME XXX -- add explanation about how and why Octave was written. +@c +@c XXX FIXME XXX -- add a sentence or two explaining that we could +@c always use more funding. + +@menu +* Running Octave:: +* Simple Examples:: +* Executable Octave Programs:: +* Comments:: +* Errors:: +@end menu + +@node Running Octave, Simple Examples, Introduction, Introduction +@section Running Octave + +On most systems, the way to invoke Octave is with the shell command +@samp{octave}. Octave displays an initial message and then a prompt +indicating it is ready to accept input. You can begin typing Octave +commands immediately afterward. + +If you get into trouble, you can usually interrupt Octave by typing +@kbd{Control-C} (usually written @kbd{C-c} for short). @kbd{C-c} gets +its name from the fact that you type it by holding down the @kbd{CTRL} +key and then pressing @kbd{c}. Doing this will normally return you to +Octave's prompt. + +To exit Octave, type @samp{quit}, or @samp{exit} at the Octave prompt. + +@cindex exiting octave +@cindex quitting octave +@findex exit +@findex quit + +On systems that support job control, you can suspend Octave by sending +it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}. + +@node Simple Examples, Executable Octave Programs, Running Octave, Introduction +@section Simple Examples + +The following chapters describe all of Octave's features in detail, but +before doing that, it might be helpful to give a sampling of some of its +capabilities. + +If you are new to Octave, I recommend that you try these examples to +begin learning Octave by using it. Lines marked with @samp{octave:13>} +are lines you type, ending each with a carriage return. Octave will +respond with an answer, or by displaying a graph. + +@unnumberedsubsec Creating a Matrix + +To create a new matrix and store it in a variable so that it you can +refer to it later, type the command + +@example +octave:1> a = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ] +@end example + +@noindent +Octave will respond by printing the matrix in neatly aligned columns. +Ending a command with a semicolon tells Octave to not print the result +of a command. For example + +@example +octave:2> b = rand (3, 2); +@end example + +@noindent +will create a 3 row, 2 column matrix with each element set to a random +value between zero and one. + +To display the value of any variable, simply type the name of the +variable. For example, to display the value stored in the matrix +@samp{b}, type the command + +@example +octave:3> b +@end example + +@unnumberedsubsec Matrix Arithmetic + +Octave has a convenient operator notation for performing matrix +arithmetic. For example, to multiply the matrix @code{a} by a scalar +value, type the command + +@example +octave:4> 2 * a +@end example + +To multiply the two matrices @var{a} and @var{b}, type the command + +@example +octave:5> a * b +@end example + +To form the matrix product +@iftex +@tex + $a^Ta$, +@end tex +@end iftex +@ifinfo + @code{transpose (a) * a}, +@end ifinfo +type the command + +@example +octave:6> a' * a +@end example + +@unnumberedsubsec Solving Linear Equations + +To solve the set of linear equations +@iftex +@tex + ${\bf Ax} = {\bf b}$, +@end tex +@end iftex +@ifinfo +@code{Ax = b}, +@end ifinfo +use the left division operator, @samp{\}: + +@example +octave:7> a \ b +@end example + +@noindent +This is conceptually equivalent to +@iftex +@tex + ${\bf A}^{-1}{\bf b}$, +@end tex +@end iftex +@ifinfo +inv (A) * b, +@end ifinfo +but avoids computing the inverse of a matrix directly. + +If the coefficient matrix is singular, Octave will print a warning +message and compute a minimum norm solution. + +@unnumberedsubsec Integrating Differential Equations + +Octave has built-in functions for solving nonlinear differential +equations of the form +@iftex +@tex +$$ + {dx \over dt} = f(x,t), \qquad {\rm with} x(t=t_0) = x_0 +$$ +@end tex +@end iftex +@ifinfo + +@example +dx +-- = f (x, t) +dt +@end example + +@noindent +with the initial condition + +@example +x(t = t0) = x0 +@end example +@end ifinfo + +@noindent +For Octave to integrate equations of this form, you must first provide a +definition of the function +@iftex +@tex +$f (x, t)$. +@end tex +@end iftex +@ifinfo +@code{f(x,t)}. +@end ifinfo +This is straightforward, and may be accomplished by entering the +function body directly on the command line. For example, the following +commands define the right hand side function for an interesting pair of +nonlinear differential equations. Note that while you are entering a +function, Octave responds with a different prompt, to indicate that it +is waiting for you to complete your input. + +@example +octave:8> function xdot = f (x, t) +> +> r = 0.25; +> k = 1.4; +> a = 1.5; +> b = 0.16; +> c = 0.9; +> d = 0.8; +> +> xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1)); +> xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); +> +> endfunction +@end example + +@noindent +Given the initial condition + +@example +x0 = [1; 2]; +@end example + +@noindent +and the set of output times as a column vector (note that the first +output time corresponds to the initial condition given above) + +@example +t = linspace (0, 50, 200)'; +@end example + +@noindent +it is easy to integrate the set of differential equations: + +@example +x = lsode ("f", x0, t); +@end example + +@noindent +The function @samp{lsode} uses the Livermore Solver for Ordinary +Differential Equations, described in A. C. Hindmarsh, @cite{ODEPACK, a +Systematized Collection of ODE Solvers}, in: Scientific Computing, R. S. +Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55--64. + +@unnumberedsubsec Producing Graphical Output + +To display the solution of the previous example graphically, use the +command + +@example +plot (t, x) +@end example + +If you are using the X Window System, Octave will automatically create +a separate window to display the plot. If you are using a terminal that +supports some other graphics commands, you will need to tell Octave what +kind of terminal you have. Type the command + +@example +set term +@end example + +@noindent +to see a list of the supported terminal types. Octave uses +@code{gnuplot} to display graphics, and can display graphics on any +terminal that is supported by @code{gnuplot}. + +To capture the output of the plot command in a file rather than sending +the output directly to your terminal, you can use a set of commands like +this + +@example +@group +set term postscript +set output "foo.ps" +replot +@end group +@end example + +@noindent +This will work for other types of output devices as well. Octave's +@samp{set} command is really just piped to the @code{gnuplot} +subprocess, so that once you have a plot on the screen that you like, +you should be able to do something like this to create an output file +suitable for your graphics printer. + +Or, you can eliminate the intermediate file by using commands like this + +@example +@group +set term postscript +set output "|lpr -Pname_of_your_graphics_printer" +replot +@end group +@end example + +@unnumberedsubsec Editing What You Have Typed + +At the Octave prompt, you can recall, edit, and reissue previous +commands using Emacs- or vi-style editing commands. The default +keybindings use Emacs-style commands. For example, to recall the +previous command, type @kbd{Control-P} (usually written @kbd{C-p} for +short). @kbd{C-p} gets its name from the fact that you type it by +holding down the @kbd{CTRL} key and then pressing @kbd{p}. Doing this +will normally bring back the previous line of input. @kbd{C-n} will +bring up the next line of input, @kbd{C-b} will move the cursor backward +on the line, @kbd{C-f} will move the cursor forward on the line, etc. + +A complete description of the command line editing capability is given +in this manual in @ref{Command Line Editing}. + +@unnumberedsubsec Getting Help + +Octave has an extensive help facility. The same documentation that is +available in printed form is also available from the Octave prompt, +because both forms of the documentation are created from the same input +file. + +In order to get good help you first need to know the name of the command +that you want to use. This name of the function may not always be +obvious, but a good place to start is to just type @code{help}. +This will show you all the operators, reserved words, functions, +built-in variables, and function files. You can then get more +help on anything that is listed by simply including the name as an +argument to help. For example, + +@example +help plot +@end example + +@noindent +will display the help text for the @code{plot} function. + +Octave sends output that is too long to fit on one screen through a +pager like @code{less} or @code{more}. Type a carriage return to +advance one line, a space character to advance one page, and @samp{q} to +exit the pager. + +@unnumberedsubsubsec Help via Info + +The part of Octave's help facility that allows you to read the complete +text of the printed manual from within Octave uses a program called +Info. When you invoke Info you will be put into a menu driven program +that contains the entire Octave manual. Help for using Info is provided +in this manual in @ref{Using Info}. + +@node Executable Octave Programs, Comments, Simple Examples, Introduction +@section Executable Octave Programs +@cindex executable scripts +@cindex scripts, executable +@cindex self contained programs +@cindex program, self contained +@cindex @samp{#!} + +Once you have learned Octave, you may want to write self-contained +Octave scripts, using the @samp{#!} script mechanism. You can do this +on many Unix systems @footnote{The @samp{#!} mechanism works on Unix +systems derived from Berkeley Unix, System V Release 4, and some System +V Release 3 systems.} (and someday on GNU). + +For example, you could create a text file named @file{hello}, containing +the following lines: + +@example +#! /usr/local/bin/octave -qf + +# a sample Octave program +printf ("Hello, world!\n"); +@end example + +@noindent +After making this file executable (with the @code{chmod} command), you +can simply type: + +@example +hello +@end example + +@noindent +at the shell, and the system will arrange to run Octave @footnote{The +line beginning with @samp{#!} lists the full file name of an interpreter +to be run, and an optional initial command line argument to pass to that +interpreter. The operating system then runs the interpreter with the +given argument and the full argument list of the executed program. The +first argument in the list is the full file name of the Octave program. +The rest of the argument list will either be options to Octave, or data +files, or both. The @code{-qf} option is usually specified in +stand-alone Octave programs to prevent them from printing the normal +startup message, and to keep them from behaving differently depending on +the contents of a particular user's @file{~/.octaverc} file. +@xref{Invoking Octave}.} as if you had typed: + +@example +octave hello +@end example + +@noindent +Self-contained Octave scripts are useful when you want to write a +program which users can invoke without knowing that the program is +written in the Octave language. + +@node Comments, Errors, Executable Octave Programs, Introduction +@section Comments in Octave Programs +@cindex @samp{#} +@cindex @samp{%} +@cindex comments +@cindex use of comments +@cindex documenting Octave programs +@cindex programs, documenting + +A @dfn{comment} is some text that is included in a program for the sake +of human readers, and that is not really part of the program. Comments +can explain what the program does, and how it works. Nearly all +programming languages have provisions for comments, because programs are +typically hard to understand without them. + +In the Octave language, a comment starts with either the sharp sign +character, @samp{#}, or the percent symbol @samp{%} and continues to the +end of the line. The Octave interpreter ignores the rest of a +line following a sharp sign or percent symbol. For example, we could +have put the following into the function @code{f}: + +@smallexample +function xdot = f (x, t) + +# usage: f (x, t) +# +# This function defines the right-hand-side functions for a set of +# nonlinear differential equations. + + r = 0.25 + + and so on... + +endfunction +@end smallexample + +The @code{help} command (@pxref{Help}) is able to find the first block +of comments in a function (even those that are composed directly on the +command line). This means that users of Octave can use the same +commands to get help for built-in functions, and for functions that you +have defined. For example, after defining the function @code{f} above, +the command + +@example +help f +@end example + +@noindent +produces the output + +@smallexample + usage: f (x, t) + + This function defines the right-hand-side functions for a set of + nonlinear differential equations. +@end smallexample + +Although it is possible to put comment lines into keyboard-composed +throw-away Octave programs, it usually isn't very useful, because the +purpose of a comment is to help you or another person understand the +program at a later time. + +@node Errors, , Comments, Introduction +@section Errors + +There are two classes of errors that Octave produces when it encounters +input that it is unable to understand, or when it is unable to perform +an action. + +A @dfn{parse error} occurs if Octave cannot understand something you +have typed. For example, if you misspell a keyword, + +@example +octave:13> functon y = f (x) y = x^2; endfunction +@end example + +@noindent +Octave will respond immediately with a message like this: + +@example +parse error: + + functon y = f (x) y = x^2; endfunction + ^ +@end example + +@noindent +For most parse errors, Octave uses a caret (@samp{^}) to mark the point +on the line where it was unable to make sense of your input. In this +case, Octave generated an error message because the keyword +@code{function} was misspelled. Instead of seeing @samp{function f}, +Octave saw two consecutive variable names, which is invalid in this +context. It marked the error at the @code{y} because the first name by +itself was accepted as valid input. + +Another class of error message occurs occurs at evaluation time. These +errors are called @dfn{run-time errors}, or sometimes +@dfn{evaluation errors} because they occur when your program is being +@dfn{run}, or @dfn{evaluated}. For example, if after correcting the +mistake in the previous function definition, you type + +@example +octave:13> f () +@end example + +@noindent +Octave will respond with + +@example +error: `x' undefined near line 1 column 24 +error: evaluating expression near line 1, column 24 +error: evaluating assignment expression near line 1, column 22 +error: called from `f' +@end example + +This error message has several parts, and gives you quite a bit of +information to help you locate the source of the error. The messages +are generated from the point of the innermost error, and provide a +traceback of enclosing expression and function calls. + +In the example above, the first line indicates that a variable named +@samp{x} was found to be undefined near line 1 and column 24 of some +function or expression. For errors occurring within functions, lines +are numbered beginning with the line containing the @samp{function} +keyword. For errors occurring at the top level, the line number +indicates the input line number, which is usually displayed in the +prompt string. + +The second and third lines in the example indicate that the error +occurred within an assignment expression, and the last line of the error +message indicates that the error occurred within the function @samp{f}. +If the function @samp{f} had been called from another function, say +@samp{g}, the list of errors would have ended with one more line: + +@example +error: called from `g' +@end example + +These lists of function calls usually make it fairly easy to trace the +path your program took before the error occurred, and to correct the +error before trying again.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/invoke.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,203 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Invoking Octave, Expressions, Introduction, Top +@chapter Invoking Octave + +Normally, Octave is used interactively by running the program +@samp{octave} without any arguments. Once started, Octave reads +commands from the terminal until you tell it to exit. + +You can also specify the name of a file on the command line, and Octave +will read and execute the commands from the named file and then exit +when it is finished. + +You can further control how Octave starts up by using the command-line +options described in the next section, and Octave itself can remind you +of the options available. Type + +@example +octave --help +@end example + +@noindent +to display all available options and briefly describe their use +(@samp{octave -h} is a shorter equivalent). + +@menu +* Command Line Options:: +* Startup Files:: +@end menu + +@node Command Line Options, Startup Files, Invoking Octave, Invoking Octave +@section Command Line Options +@cindex Octave command options +@cindex command options +@cindex options, Octave command + +@table @code +@item --debug +@itemx -d +@cindex @code{--debug} +@cindex @code{-d} +Enter parser debugging mode. Using this option will cause Octave's +parser to print a lot of information about the commands it reads, and is +probably only useful if you are actually trying to debug the parser. + +@item --echo-commands +@itemx -x +@cindex @code{--echo-commands} +@cindex @code{-x} +Echo commands as they are executed. + +@item --exec-path @var{path} +@cindex @code{--exec-path @var{path}} +Specify the path to search for programs to run. The value of @var{path} +specified on the command line will override any value of +@samp{OCTAVE_EXEC_PATH} found in the environment, but not any +@samp{EXEC_PATH = "path"} commands found in the system or user startup +files. + +@item --help +@itemx -h +@itemx -? +@cindex @code{--help} +@cindex @code{-h} +@cindex @code{-?} +Print short help message and exit. + +@item --ignore-init-file +@itemx --norc +@itemx -f +@cindex @code{--ignore-init-file} +@cindex @code{--norc} +@cindex @code{-f} +Don't read any of the system or user initialization files at startup. + +@item --info-file @var{filename} +@cindex @code{--info-file @var{filename}} +Specify the name of the info file to use. The value of @var{filename} +specified on the command line will override any value of +@samp{OCTAVE_INFO_FILE} found in the environment, but not any +@samp{INFO_FILE = "filename"} commands found in the system or user +startup files. + +@item --info-program @var{program} +@cindex @code{--info-program @var{program}} +Specify the name of the info program to use. The value of @var{program} +specified on the command line will override any value of +@samp{OCTAVE_INFO_PROGRAM} found in the environment, but not any +@samp{INFO_PROGRAM = "program"} commands found in the system or user +startup files. + +@item --interactive +@itemx -i +@cindex @code{--interactive} +@cindex @code{-i} +Force interactive behavior. + +@item --no-line-editing +@cindex @code{--no-line-editing} +Disable command-line editing and history. + +@item --path @var{path} +@itemx -p @var{path} +@cindex @code{--path @var{path}} +@cindex @code{-p @var{path}} +Specify the path to search for function files. The value of @var{path} +specified on the command line will override any value of +@samp{OCTAVE_PATH} found in the environment, but not any +@samp{LOADPATH = "path"} commands found in the system or user startup +files. + +@item --silent +@itemx --quiet +@itemx -q +@cindex @code{--silent} +@cindex @code{--quiet} +@cindex @code{-q} +Don't print message at startup. + +@item --traditional +@cindex @code{--traditional} +Set initial values for user-preference variables to the following +values for compatibility with Matlab. + +@example +PS1 = ">> " +PS2 = "" +beep_on_error = 1 +default_save_format = "mat-binary" +define_all_return_values = 1 +do_fortran_indexing = 1 +empty_list_elements_ok = 1 +implicit_str_to_num_ok = 1 +ok_to_lose_imaginary_part = 1 +page_screen_output = 0 +prefer_column_vectors = 0 +prefer_zero_one_indexing = 1 +print_empty_dimensions = 0 +treat_neg_dim_as_zero = 1 +warn_function_name_clash = 0 +whitespace_in_literal_matrix = "traditional" +@end example + +@item --verbose +@itemx -V +@cindex @code{--verbose} +@cindex @code{-V} +Turn on verbose output. + +@item --version +@itemx -v +@cindex @code{--version} +@cindex @code{-v} +Print the program version number and exit. + +@item @var{file} +Execute commands from @var{file}. +@end table + +@node Startup Files, , Command Line Options, Invoking Octave +@section Startup Files +@cindex initialization +@cindex startup + +When Octave starts, it looks for commands to execute from the following +files: + +@cindex startup files + +@table @code +@item OCTAVE_HOME/lib/octave/VERSION/m/startup/octaverc +Where @code{OCTAVE_HOME} is the directory in which all of Octave is +installed (the default is @file{/usr/local}), and @code{VERSION} is the +version number of Octave. This file is provided so that changes to the +default Octave environment can be made globally for all users. Some +care should be taken when making changes to this file, since all users +of Octave at your site will be affected. + +@item ~/.octaverc +@cindex @code{~/.octaverc} +This file is normally used to make personal changes to the default +Octave environment. + +@item .octaverc +@cindex @code{.octaverc} +This file can be used to make changes to the default Octave environment +for a particular project. Octave searches for this file after it reads +@file{~/.octaverc}, so any use of the @code{cd} command in the +@file{~/.octaverc} file will affect the directory that Octave searches +for the file @file{.octaverc}. + +If you start Octave in your home directory, commands from from the file +@file{~/.octaverc} will only be executed once. +@end table + +A message will be displayed as each of these files is read if you invoke +Octave with the @code{--verbose} option but without the @code{--silent} +option. + +Startup files may contain any valid Octave commands, including multiple +function definitions.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/io.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,1153 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Input and Output, Special Matrices, Audio Processing, Top +@chapter Input and Output + +There are two distinct classes of input and output functions. The first +set are modeled after the functions available in @sc{Matlab}. The +second set are modeled after the standard I/O library used by the C +programming language. The C-style I/O functions offer more flexibility +and control over the output, but are not quite as easy to use as the +simpler @sc{Matlab}-style I/O functions. + +When running interactively, Octave normally sends any output intended +for your terminal that is more than one screen long to a paging program, +such as @code{less} or @code{more}. This avoids the problem of having +a large volume of output stream by before you can read it. With +@code{less} (and some versions of @code{more}) it also allows you to +scan forward and backward, and search for specific items. + +@findex fflush +No output is displayed by the pager until just before Octave is ready to +print the top level prompt, or read from the standard input using the +@code{fscanf} or @code{scanf} functions. This means that there may be +some delay before any output appears on your screen if you have asked +Octave to perform a significant amount of work with a single command +statement. The function @code{fflush} may be used to force output to be +sent to the pager immediately. @xref{C-Style I/O Functions}. + +You can select the program to run as the pager by setting the variable +@code{PAGER}, and you can turn paging off by setting the value of the +variable @code{page_screen_output} to the string @samp{"false"}. +@xref{User Preferences}. + +@menu +* Basic Input and Output:: +* C-Style I/O Functions:: +@end menu + +@node Basic Input and Output, C-Style I/O Functions, Input and Output, Input and Output +@section Basic Input and Output + +Since Octave normally prints the value of an expression as soon as it +has been evaluated, the simplest of all I/O functions is a simple +expression. For example, the following expression will display the +value of pi + +@example +octave:13> pi +pi = 3.1416 +@end example + +This works well as long as it is acceptable to have the name of the +variable (or @samp{ans}) printed along with the value. To print the +value of a variable without printing its name, use the function +@code{disp}. For example, the following expression + +@findex disp + +@example +disp ("The value of pi is:"), disp (pi) +@end example + +@noindent +will print + +@example +The value of pi is: +3.1416 +@end example + +@noindent +Note that the output from @code{disp} always ends with a newline. + +A simple way to control the output format is with the @code{format} +statement. For example, to print more digits for pi you can use the +command + +@example +format long +@end example + +@noindent +Then the expression above will print + +@example +The value of pi is: +3.14159265358979 +@end example + +@findex format + +Here is a summary of the options for @code{format}: + +@table @code +@item short +This is the default format. Octave will try to print numbers with at +least 5 significant figures within a field that is a maximum of 10 +characters wide. + +If Octave is unable to format a matrix so that columns line up on the +decimal point and all the numbers fit within the maximum field width, +it switches to an @samp{e} format. + +@item long +Octave will try to print numbers with at least 15 significant figures +within a field that is a maximum of 24 characters wide. + +As will the @samp{short} format, Octave will switch to an @samp{e} +format if it is unable to format a matrix so that columns line up on the +decimal point and all the numbers fit within the maximum field width. + +@item long e +@itemx short e +The same as @samp{format long} or @samp{format short} but always display +output with an @samp{e} format. For example, with the @samp{short e} +format, pi is displayed as + +@example + 3.14e+00 +@end example + +@item long E +@itemx short E +The same as @samp{format long e} or @samp{format short e} but always +display output with an uppercase @samp{E} format. For example, with +the @samp{long E} format, pi is displayed as + +@example + 3.14159265358979E+00 +@end example + +@item free +@itemx none +Print output in free format, without trying to line up columns of +matrices on the decimal point. This also causes complex numbers to be +formatted like this @samp{(0.604194, 0.607088)} instead of like this +@samp{0.60419 + 0.60709i}. + +@item bank +Print in a fixed format with two places to the right of the decimal +point. + +@item + +Print a @samp{+} symbol for nonzero matrix elements and a space for zero +matrix elements. This format can be very useful for examining the +structure of a large matrix. + +@item hex +Print the hexadecimal representation numbers as they are stored in +memory. For example, on a workstation which stores 8 byte real values +in IEEE format with the least significant byte first, the value of +@code{pi} when printed in @code{hex} format is @code{400921fb54442d18}. +This format only works for numeric values. + +@item bit +Print the bit representation of numbers as stored in memory. +For example, the value of @code{pi} is +@code{0100000000001001001000011111101101010100010001000010110100011000} +when printed in bit format on a workstation which stores 8 byte real +values in IEEE format with the least significant byte first. +This format only works for numeric types. +@end table + +The @code{input} function may be used for prompting the user for a +value and storing the result in a variable. For example, +@findex input + +@example +input ("Pick a number, any number! ") +@end example + +@noindent +prints the prompt + +@example +Pick a number, any number! +@end example + +@noindent +and waits for the user to enter a value. The string entered by the user +is evaluated as an expression, so it may be a literal constant, a +variable name, or any other valid expression. + +Currently, @code{input} only returns one value, regardless of the number +of values produced by the evaluation of the expression. + +If you are only interested in getting a literal string value, you can +call @code{input} with the character string @samp{s} as the second +argument. This tells Octave to return the string entered by the user +directly, without evaluating it first. + +Because there may be output waiting to be displayed by the pager, it is +a good idea to always call @code{fflush (stdout)} before calling +@code{input}. This will ensure that all pending output is written to +the screen before your prompt. @xref{C-Style I/O Functions}. + +@findex keyboard + +The second input function, @code{keyboard}, is normally used for simple +debugging. Using @code{keyboard}, it is possible to examine the values +of variables within a function, and to assign newassign new variables +Like @code{input}, it prompts the user for input, but no value is +returned, and it continues to prompt for input until the user types +@samp{quit}, or @samp{exit}. + +If @code{keyboard} is invoked without any arguments, a default prompt of +@samp{debug> } is used. + +For both of these functions, the normal command line history and editing +functions are available at the prompt. + +@findex save +To save variables in a file, use the @code{save} command. For example, +the command + +@example +save data a b c +@end example + +@noindent +saves the variables @samp{a}, @samp{b}, and @samp{c} in the file +@file{data}. + +@vindex default_save_format +The @var{save} command can read files in Octave's text and binary +formats as well as @sc{Matlab}'s binary format. You can specify the default +format with the built-in variable @var{default_save_format} using one of +the following values: @code{"binary"} or @code{"mat-binary"}. The +initial default save format is Octave's text format. + +@vindex save_precision +You can use the built-in variable @code{save_precision} to specify the +number of digits to keep when saving data in text format. + +The list of variables to save may include wildcard patterns containing +the following special characters: +@table @code +@item ? +Match any single character. + +@item * +Match zero or more characters. + +@item [ @var{list} ] +Match the list of characters specified by @var{list}. If the first +character is @code{!} or @code{^}, match all characters except those +specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will +match all lower and upper case alphabetic characters. +@end table + +The following options may be specified for @code{save}. + +@ftable @code +@item -ascii +Save the data in Octave's text data format. Using this flag overrides +the value of the built-in variable @code{default_save_format}. + +@item -binary +Save the data in Octave's binary data format. Using this flag overrides +the value of the built-in variable @code{default_save_format}. + +@item -float-binary +Save the data in Octave's binary data format but only using single +precision. Using this flag overrides the value of the built-in variable +@code{default_save_format}. You should use this format only if you +know that all the values to be saved can be represented in single +precision. + +@item -mat-binary +Save the data in @sc{Matlab}'s binary data format. Using this flag overrides +the value of the built-in variable @code{default_save_format}. + +@item -save-builtins +Force Octave to save the values of built-in variables too. By default, +Octave does not save built-in variables. +@end ftable + +@findex load +Saving global variables also saves the global status of the variable, so +that if it is restored at a later time using @samp{load}, it will be +restored as a global variable. + +To restore the values from a file, use the @code{load} command. For +example, to restore the variables saved in the file @file{data}, use the +command + +@example +load data +@end example + +Octave will refuse to overwrite existing variables unless you use the +option @samp{-force}. + +If a variable that is not marked as global is loaded from a file when a +global symbol with the same name already exists, it is loaded in the +global symbol table. Also, if a variable is marked as global in a file +and a local symbol exists, the local symbol is moved to the global +symbol table and given the value from the file. Since it seems that +both of these cases are likely to be the result of some sort of error, +they will generate warnings. + +As with @code{save}, you may specify a list of variables and @code{load} +will only extract those variables with names that match. + +The @code{load} command can read data stored in Octave's text and +binary formats, and @sc{Matlab}'s binary format. It will automatically +detect the type of file and do conversion from different floating point +formats (currently only IEEE big and little endian, though other formats +may added in the future). + +The following options may be specified for @code{load}. + +@ftable @code +@item -force +Force variables currently in memory to be overwritten by variables with +the same name found in the file. + +@item -ascii +Force Octave to assume the file is in Octave's text format. + +@item -binary +Force Octave to assume the file is in Octave's binary format. + +@item -mat-binary +Force Octave to assume the file is in @sc{Matlab}'s binary format. +@end ftable + +@node C-Style I/O Functions, , Basic Input and Output, Input and Output +@section C-Style I/O Functions + +The C-style input and output functions provide most of the functionality +of the C programming language's standard I/O library. The argument +lists for some of the input functions are slightly different, however, +because Octave has no way of passing arguments by reference. + +In the following, @var{file} refers either to an integer file number +(as returned by @file{fopen}) or a file name. + +There are three files that are always available: + +@table @code +@item stdin +The standard input stream (file number 0). When Octave is used +interactively, this is filtered through the command line editing +functions. + +@item stdout +The standard output stream (file number 1). Data written to the +standard output is normally filtered through the pager. + +@item stderr +The standard error stream (file number 2). Even if paging is turned on, +the standard error is not sent to the pager. It is useful for error +messages and prompts. +@end table + +You should always use the symbolic names given in the table above, +rather than referring to these files by number, since it will make +your programs clearer. + +@menu +* Opening and Closing Files:: +* Formatted Output:: +* Output Conversion Syntax:: +* Table of Output Conversions:: +* Integer Conversions:: +* Floating-Point Conversions:: +* Other Output Conversions:: +* Formatted Input:: +* Input Conversion Syntax:: +* Table of Input Conversions:: +* Numeric Input Conversions:: +* String Input Conversions:: +* Binary I/O:: +* Other I/O Functions:: +@end menu + +@node Opening and Closing Files, Formatted Output, C-Style I/O Functions, C-Style I/O Functions +@subsection Opening and Closing Files + +@findex fopen +To open a file, use the function @code{fopen (name, mode)}. It returns +an integer value that may be used to refer to the file later. The +second argument is a one or two character string that specifies whether +the file is to be opened for reading, writing, or both. + +For example, + +@example +myfile = fopen ("splat.dat", "r"); +@end example + +@noindent +opens the file @file{splat.dat} for reading. Opening a file that is +already open has no effect. + +@c XXX FIXME XXX -- There still seem to be some minor bugs with fopen. +@c You should probably get an error if you try to reopen a file with a +@c different mode. You should probably get a warning if the file is +@c already open, etc. + + +The possible values @samp{mode} may have are + +@table @asis +@item @samp{r} +Open a file for reading. + +@item @samp{w} +Open a file for writing. The previous contents are discared. + +@item @samp{a} +Open or create a file for writing at the end of the file. + +@item @samp{r+} +Open an existing file for reading and writing. + +@item @samp{w+} +Open a file for reading or writing. The previous contents are +discared. + +@item @samp{a+} +Open or create a file for reading or writing at the end of the +file. +@end table + +@findex fclose +To close a file once you are finished with it, use the function +@code{fclose (@var{file})}. If an error is encountered while trying to close +the file, an error message is printed and @code{fclose} returns 0. +Otherwise, it returns 1. + +@node Formatted Output, Output Conversion Syntax, Opening and Closing Files, C-Style I/O Functions +@subsection Formatted Output + +This section describes how to call @code{printf} and related functions. + +The following functions are available for formatted output. They are +modelled after the C language functions of the same name. + +@ftable @code +@item printf (@var{template}, ...) +The @code{printf} function prints the optional arguments under the +control of the template string @var{template} to the stream +@code{stdout}. + +@item fprintf (@var{file}, @var{template}, ...) +This function is just like @code{printf}, except that the output is +written to the stream @var{file} instead of @code{stdout}. + +@item sprintf (@var{template}, ...) +This is like @code{printf}, except that the output is written to a +string. Unlike the C library function, which requires you to provide a +suitably sized string as an argument, Octave's @code{sprintf} function +returns the string, automatically sized to hold all of the items +converted. +@end ftable + +The @code{printf} function can be used to print any number of arguments. +The template string argument you supply in a call provides +information not only about the number of additional arguments, but also +about their types and what style should be used for printing them. + +Ordinary characters in the template string are simply written to the +output stream as-is, while @dfn{conversion specifications} introduced by +a @samp{%} character in the template cause subsequent arguments to be +formatted and written to the output stream. For example, +@cindex conversion specifications (@code{printf}) + +@smallexample +pct = 37; +filename = "foo.txt"; +printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n", + filename, pct); +@end smallexample + +@noindent +produces output like + +@smallexample +Processing of `foo.txt' is 37% finished. +Please be patient. +@end smallexample + +This example shows the use of the @samp{%d} conversion to specify that a +scalar argument should be printed in decimal notation, the @samp{%s} +conversion to specify printing of a string argument, and the @samp{%%} +conversion to print a literal @samp{%} character. + +There are also conversions for printing an integer argument as an +unsigned value in octal, decimal, or hexadecimal radix (@samp{%o}, +@samp{%u}, or @samp{%x}, respectively); or as a character value +(@samp{%c}). + +Floating-point numbers can be printed in normal, fixed-point notation +using the @samp{%f} conversion or in exponential notation using the +@samp{%e} conversion. The @samp{%g} conversion uses either @samp{%e} +or @samp{%f} format, depending on what is more appropriate for the +magnitude of the particular number. + +You can control formatting more precisely by writing @dfn{modifiers} +between the @samp{%} and the character that indicates which conversion +to apply. These slightly alter the ordinary behavior of the conversion. +For example, most conversion specifications permit you to specify a +minimum field width and a flag indicating whether you want the result +left- or right-justified within the field. + +The specific flags and modifiers that are permitted and their +interpretation vary depending on the particular conversion. They're all +described in more detail in the following sections. + +@node Output Conversion Syntax, Table of Output Conversions, Formatted Output, C-Style I/O Functions +@subsection Output Conversion Syntax + +This section provides details about the precise syntax of conversion +specifications that can appear in a @code{printf} template +string. + +Characters in the template string that are not part of a +conversion specification are printed as-is to the output stream. + +The conversion specifications in a @code{printf} template string have +the general form: + +@smallexample +% @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion} +@end smallexample + +For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-} +is a flag, @samp{10} specifies the field width, the precision is +@samp{8}, the letter @samp{l} is a type modifier, and @samp{d} specifies +the conversion style. (This particular type specifier says to print a +numeric argument in decimal notation, with a minimum of 8 digits +left-justified in a field at least 10 characters wide.) + +In more detail, output conversion specifications consist of an +initial @samp{%} character followed in sequence by: + +@itemize @bullet +@item +Zero or more @dfn{flag characters} that modify the normal behavior of +the conversion specification. +@cindex flag character (@code{printf}) + +@item +An optional decimal integer specifying the @dfn{minimum field width}. +If the normal conversion produces fewer characters than this, the field +is padded with spaces to the specified width. This is a @emph{minimum} +value; if the normal conversion produces more characters than this, the +field is @emph{not} truncated. Normally, the output is right-justified +within the field. +@cindex minimum field width (@code{printf}) + +You can also specify a field width of @samp{*}. This means that the +next argument in the argument list (before the actual value to be +printed) is used as the field width. The value is rounded to the +nearest integer. If the value is negative, this means to set the +@samp{-} flag (see below) and to use the absolute value as the field +width. + +@item +An optional @dfn{precision} to specify the number of digits to be +written for the numeric conversions. If the precision is specified, it +consists of a period (@samp{.}) followed optionally by a decimal integer +(which defaults to zero if omitted). +@cindex precision (@code{printf}) + +You can also specify a precision of @samp{*}. This means that the next +argument in the argument list (before the actual value to be printed) is +used as the precision. The value must be an integer, and is ignored +if it is negative. + +@item +An optional @dfn{type modifier character}. This character is ignored by +Octave's @code{printf} function, but is recognized to provide +compatibility with the C language @code{printf}. + +@item +A character that specifies the conversion to be applied. +@end itemize + +The exact options that are permitted and how they are interpreted vary +between the different conversion specifiers. See the descriptions of the +individual conversions for information about the particular options that +they use. + +@node Table of Output Conversions, Integer Conversions, Output Conversion Syntax, C-Style I/O Functions +@subsection Table of Output Conversions +@cindex output conversions, for @code{printf} + +Here is a table summarizing what all the different conversions do: + +@table @asis +@item @samp{%d}, @samp{%i} +Print an integer as a signed decimal number. @xref{Integer +Conversions}, for details. @samp{%d} and @samp{%i} are synonymous for +output, but are different when used with @code{scanf} for input +(@pxref{Table of Input Conversions}). + +@item @samp{%o} +Print an integer as an unsigned octal number. @xref{Integer +Conversions}, for details. + +@item @samp{%u} +Print an integer as an unsigned decimal number. @xref{Integer +Conversions}, for details. + +@item @samp{%x}, @samp{%X} +Print an integer as an unsigned hexadecimal number. @samp{%x} uses +lower-case letters and @samp{%X} uses upper-case. @xref{Integer +Conversions}, for details. + +@item @samp{%f} +Print a floating-point number in normal (fixed-point) notation. +@xref{Floating-Point Conversions}, for details. + +@item @samp{%e}, @samp{%E} +Print a floating-point number in exponential notation. @samp{%e} uses +lower-case letters and @samp{%E} uses upper-case. @xref{Floating-Point +Conversions}, for details. + +@item @samp{%g}, @samp{%G} +Print a floating-point number in either normal or exponential notation, +whichever is more appropriate for its magnitude. @samp{%g} uses +lower-case letters and @samp{%G} uses upper-case. @xref{Floating-Point +Conversions}, for details. + +@item @samp{%c} +Print a single character. @xref{Other Output Conversions}. + +@item @samp{%s} +Print a string. @xref{Other Output Conversions}. + +@item @samp{%%} +Print a literal @samp{%} character. @xref{Other Output Conversions}. +@end table + +If the syntax of a conversion specification is invalid, unpredictable +things will happen, so don't do this. If there aren't enough function +arguments provided to supply values for all the conversion +specifications in the template string, or if the arguments are not of +the correct types, the results are unpredictable. If you supply more +arguments than conversion specifications, the extra argument values are +simply ignored; this is sometimes useful. + +@node Integer Conversions, Floating-Point Conversions, Table of Output Conversions, C-Style I/O Functions +@subsection Integer Conversions + +This section describes the options for the @samp{%d}, @samp{%i}, +@samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion +specifications. These conversions print integers in various formats. + +The @samp{%d} and @samp{%i} conversion specifications both print an +numeric argument as a signed decimal number; while @samp{%o}, +@samp{%u}, and @samp{%x} print the argument as an unsigned octal, +decimal, or hexadecimal number (respectively). The @samp{%X} conversion +specification is just like @samp{%x} except that it uses the characters +@samp{ABCDEF} as digits instead of @samp{abcdef}. + +The following flags are meaningful: + +@table @asis +@item @samp{-} +Left-justify the result in the field (instead of the normal +right-justification). + +@item @samp{+} +For the signed @samp{%d} and @samp{%i} conversions, print a +plus sign if the value is positive. + +@item @samp{ } +For the signed @samp{%d} and @samp{%i} conversions, if the result +doesn't start with a plus or minus sign, prefix it with a space +character instead. Since the @samp{+} flag ensures that the result +includes a sign, this flag is ignored if you supply both of them. + +@item @samp{#} +For the @samp{%o} conversion, this forces the leading digit to be +@samp{0}, as if by increasing the precision. For @samp{%x} or +@samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively) +to the result. This doesn't do anything useful for the @samp{%d}, +@samp{%i}, or @samp{%u} conversions. + +@item @samp{0} +Pad the field with zeros instead of spaces. The zeros are placed after +any indication of sign or base. This flag is ignored if the @samp{-} +flag is also specified, or if a precision is specified. +@end table + +If a precision is supplied, it specifies the minimum number of digits to +appear; leading zeros are produced if necessary. If you don't specify a +precision, the number is printed with as many digits as it needs. If +you convert a value of zero with an explicit precision of zero, then no +characters at all are produced. + +@node Floating-Point Conversions, Other Output Conversions, Integer Conversions, C-Style I/O Functions +@subsection Floating-Point Conversions + +This section discusses the conversion specifications for floating-point +numbers: the @samp{%f}, @samp{%e}, @samp{%E}, @samp{%g}, and @samp{%G} +conversions. + +The @samp{%f} conversion prints its argument in fixed-point notation, +producing output of the form +@w{[@code{-}]@var{ddd}@code{.}@var{ddd}}, +where the number of digits following the decimal point is controlled +by the precision you specify. + +The @samp{%e} conversion prints its argument in exponential notation, +producing output of the form +@w{[@code{-}]@var{d}@code{.}@var{ddd}@code{e}[@code{+}|@code{-}]@var{dd}}. +Again, the number of digits following the decimal point is controlled by +the precision. The exponent always contains at least two digits. The +@samp{%E} conversion is similar but the exponent is marked with the letter +@samp{E} instead of @samp{e}. + +The @samp{%g} and @samp{%G} conversions print the argument in the style +of @samp{%e} or @samp{%E} (respectively) if the exponent would be less +than -4 or greater than or equal to the precision; otherwise they use the +@samp{%f} style. Trailing zeros are removed from the fractional portion +of the result and a decimal-point character appears only if it is +followed by a digit. + +The following flags can be used to modify the behavior: + +@c Not @samp so we can have ` ' as an item. +@table @asis +@item @samp{-} +Left-justify the result in the field. Normally the result is +right-justified. + +@item @samp{+} +Always include a plus or minus sign in the result. + +@item @samp{ } +If the result doesn't start with a plus or minus sign, prefix it with a +space instead. Since the @samp{+} flag ensures that the result includes +a sign, this flag is ignored if you supply both of them. + +@item @samp{#} +Specifies that the result should always include a decimal point, even +if no digits follow it. For the @samp{%g} and @samp{%G} conversions, +this also forces trailing zeros after the decimal point to be left +in place where they would otherwise be removed. + +@item @samp{0} +Pad the field with zeros instead of spaces; the zeros are placed +after any sign. This flag is ignored if the @samp{-} flag is also +specified. +@end table + +The precision specifies how many digits follow the decimal-point +character for the @samp{%f}, @samp{%e}, and @samp{%E} conversions. For +these conversions, the default precision is @code{6}. If the precision +is explicitly @code{0}, this suppresses the decimal point character +entirely. For the @samp{%g} and @samp{%G} conversions, the precision +specifies how many significant digits to print. Significant digits are +the first digit before the decimal point, and all the digits after it. +If the precision is @code{0} or not specified for @samp{%g} or +@samp{%G}, it is treated like a value of @code{1}. If the value being +printed cannot be expressed precisely in the specified number of digits, +the value is rounded to the nearest number that fits. + +@node Other Output Conversions, Formatted Input, Floating-Point Conversions, C-Style I/O Functions +@subsection Other Output Conversions + +This section describes miscellaneous conversions for @code{printf}. + +The @samp{%c} conversion prints a single character. The @samp{-} +flag can be used to specify left-justification in the field, but no +other flags are defined, and no precision or type modifier can be given. +For example: + +@smallexample +printf ("%c%c%c%c%c", "h", "e", "l", "l", "o"); +@end smallexample + +@noindent +prints @samp{hello}. + +The @samp{%s} conversion prints a string. The corresponding argument +must be a string. A precision can be specified to indicate the maximum +number of characters to write; otherwise characters in the string up to +but not including the terminating null character are written to the +output stream. The @samp{-} flag can be used to specify +left-justification in the field, but no other flags or type modifiers +are defined for this conversion. For example: + +@smallexample +printf ("%3s%-6s", "no", "where"); +@end smallexample + +@noindent +prints @samp{ nowhere }. + +@node Formatted Input, Input Conversion Syntax, Other Output Conversions, C-Style I/O Functions +@subsection Formatted Input + +Here are the descriptions of the functions for performing formatted +input. + +@ftable @code +@item scanf (@var{template}) +The @code{scanf} function reads formatted input from the stream +@code{stdin} under the control of the template string @var{template}. +The resulting values are returned. + +@item fscanf (@var{file}, @var{template}) +This function is just like @code{scanf}, except that the input is read +from the stream @var{file} instead of @code{stdin}. + +@item sscanf (@var{string}, @var{template}) +This is like @code{scanf}, except that the characters are taken from the +string @var{string} instead of from a stream. Reaching the end of the +string is treated as an end-of-file condition. +@end ftable + +Calls to @code{scanf} are superficially similar to calls to +@code{printf} in that arbitrary arguments are read under the control of +a template string. While the syntax of the conversion specifications in +the template is very similar to that for @code{printf}, the +interpretation of the template is oriented more towards free-format +input and simple pattern matching, rather than fixed-field formatting. +For example, most @code{scanf} conversions skip over any amount of +``white space'' (including spaces, tabs, and newlines) in the input +file, and there is no concept of precision for the numeric input +conversions as there is for the corresponding output conversions. +Ordinarily, non-whitespace characters in the template are expected to +match characters in the input stream exactly. +@cindex conversion specifications (@code{scanf}) + +When a @dfn{matching failure} occurs, @code{scanf} returns immediately, +leaving the first non-matching character as the next character to be +read from the stream, and @code{scanf} returns all the items that were +successfully converted. +@cindex matching failure, in @code{scanf} + +The formatted input functions are not used as frequently as the +formatted output functions. Partly, this is because it takes some care +to use them properly. Another reason is that it is difficult to recover +from a matching error. + +@node Input Conversion Syntax, Table of Input Conversions, Formatted Input, C-Style I/O Functions +@subsection Input Conversion Syntax + +A @code{scanf} template string is a string that contains ordinary +multibyte characters interspersed with conversion specifications that +start with @samp{%}. + +Any whitespace character in the template causes any number of whitespace +characters in the input stream to be read and discarded. The whitespace +characters that are matched need not be exactly the same whitespace +characters that appear in the template string. For example, write +@samp{ , } in the template to recognize a comma with optional whitespace +before and after. + +Other characters in the template string that are not part of conversion +specifications must match characters in the input stream exactly; if +this is not the case, a matching failure occurs. + +The conversion specifications in a @code{scanf} template string +have the general form: + +@smallexample +% @var{flags} @var{width} @var{type} @var{conversion} +@end smallexample + +In more detail, an input conversion specification consists of an initial +@samp{%} character followed in sequence by: + +@itemize @bullet +@item +An optional @dfn{flag character} @samp{*}, which says to ignore the text +read for this specification. When @code{scanf} finds a conversion +specification that uses this flag, it reads input as directed by the +rest of the conversion specification, but it discards this input, does +not use a pointer argument, and does not increment the count of +successful assignments. +@cindex flag character (@code{scanf}) + +@item +An optional decimal integer that specifies the @dfn{maximum field +width}. Reading of characters from the input stream stops either when +this maximum is reached or when a non-matching character is found, +whichever happens first. Most conversions discard initial whitespace +characters (those that don't are explicitly documented), and these +discarded characters don't count towards the maximum field width. +@cindex maximum field width (@code{scanf}) + +@item +An optional type modifier character. This character is ignored by +Octave's @code{scanf} function, but is recognized to provide +compatibility with the C language @code{scanf}. + +@item +A character that specifies the conversion to be applied. +@end itemize + +The exact options that are permitted and how they are interpreted vary +between the different conversion specifiers. See the descriptions of the +individual conversions for information about the particular options that +they allow. + +@node Table of Input Conversions, Numeric Input Conversions, Input Conversion Syntax, C-Style I/O Functions +@subsection Table of Input Conversions +@cindex input conversions, for @code{scanf} + +Here is a table that summarizes the various conversion specifications: + +@table @asis +@item @samp{%d} +Matches an optionally signed integer written in decimal. @xref{Numeric +Input Conversions}. + +@item @samp{%i} +Matches an optionally signed integer in any of the formats that the C +language defines for specifying an integer constant. @xref{Numeric +Input Conversions}. + +@item @samp{%o} +Matches an unsigned integer written in octal radix. +@xref{Numeric Input Conversions}. + +@item @samp{%u} +Matches an unsigned integer written in decimal radix. +@xref{Numeric Input Conversions}. + +@item @samp{%x}, @samp{%X} +Matches an unsigned integer written in hexadecimal radix. +@xref{Numeric Input Conversions}. + +@item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G} +Matches an optionally signed floating-point number. @xref{Numeric Input +Conversions}. + +@item @samp{%s} +Matches a string containing only non-whitespace characters. +@xref{String Input Conversions}. + +@item @samp{%c} +Matches a string of one or more characters; the number of characters +read is controlled by the maximum field width given for the conversion. +@xref{String Input Conversions}. + +@item @samp{%%} +This matches a literal @samp{%} character in the input stream. No +corresponding argument is used. +@end table + +If the syntax of a conversion specification is invalid, the behavior is +undefined. If there aren't enough function arguments provided to supply +addresses for all the conversion specifications in the template strings +that perform assignments, or if the arguments are not of the correct +types, the behavior is also undefined. On the other hand, extra +arguments are simply ignored. + +@node Numeric Input Conversions, String Input Conversions, Table of Input Conversions, C-Style I/O Functions +@subsection Numeric Input Conversions + +This section describes the @code{scanf} conversions for reading numeric +values. + +The @samp{%d} conversion matches an optionally signed integer in decimal +radix. + +The @samp{%i} conversion matches an optionally signed integer in any of +the formats that the C language defines for specifying an integer +constant. + +For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012} +could be read in as integers under the @samp{%i} conversion. Each of +these specifies a number with decimal value @code{10}. + +The @samp{%o}, @samp{%u}, and @samp{%x} conversions match unsigned +integers in octal, decimal, and hexadecimal radices, respectively. + +The @samp{%X} conversion is identical to the @samp{%x} conversion. They +both permit either uppercase or lowercase letters to be used as digits. + +Unlike the C language @code{scanf}, Octave ignores the @samp{h}, +@samp{l}, and @samp{L} modifiers. + +@node String Input Conversions, Binary I/O, Numeric Input Conversions, C-Style I/O Functions +@subsection String Input Conversions + +This section describes the @code{scanf} input conversions for reading +string and character values: @samp{%s} and @samp{%c}. + +The @samp{%c} conversion is the simplest: it matches a fixed number of +characters, always. The maximum field with says how many characters to +read; if you don't specify the maximum, the default is 1. This +conversion does not skip over initial whitespace characters. It reads +precisely the next @var{n} characters, and fails if it cannot get that +many. + +The @samp{%s} conversion matches a string of non-whitespace characters. +It skips and discards initial whitespace, but stops when it encounters +more whitespace after having read something. + +For example, reading the input: + +@smallexample + hello, world +@end smallexample + +@noindent +with the conversion @samp{%10c} produces @code{" hello, wo"}, but +reading the same input with the conversion @samp{%10s} produces +@code{"hello,"}. + +@node Binary I/O, Other I/O Functions, String Input Conversions, C-Style I/O Functions +@subsection Binary I/O + +Octave has to C-style functions for reading and writing binary data. +They are @code{fread} and @code{fwrite} and are patterned after the +standard C functions with the same names. + +@ftable @code +@item fread (@var{file}, @var{size}, @var{precision}) +This function reads data in binary form of type @var{precision} from the +specified @var{file}, which may be either a file name, or a file number +as returned from @code{fopen}. + +The argument @var{size} specifies the size of the matrix to return. It +may be a scalar or a two-element vector. If it is a scalar, +@code{fread} returns a column vector of the specified length. If it is +a two-element vector, it specifies the number of rows and columns of the +result matrix, and @code{fread} fills the elements of the matrix in +column-major order. + +The argument @var{precision} is a string specifying the type of data to +read and may be one of @code{"char"}, @code{"schar"}, @code{"short"}, +@code{"int"}, @code{"long"}, @code{"float"}, @code{"double"}, +@code{"uchar"}, @code{"ushort"}, @code{"uint"}, or @code{"ulong"}. The +default precision is @code{"uchar"}. + +The @code{fread} function returns two values, @code{data}, which is the +data read from the file, and @code{count}, which is the number of +elements read. + +@item fwrite (@var{file}, @var{data}, @var{precision}) +This function writes data in binary form of type @var{precision} to the +specified @var{file}, which may be either a file name, or a file number +as returned from @code{fopen}. + +The argument @var{data} is a matrix of values that are to be written to +the file. The values are extracted in column-major order. + +The argument @var{precision} is a string specifying the type of data to +read and may be one of @code{"char"}, @code{"schar"}, @code{"short"}, +@code{"int"}, @code{"long"}, @code{"float"}, @code{"double"}, +@code{"uchar"}, @code{"ushort"}, @code{"uint"}, or @code{"ulong"}. The +default precision is @code{"uchar"}. + +The @code{fwrite} function returns the number of elements written. + +The behavior of @code{fwrite} is undefined if the values in @var{data} +are too large to fit in the specified precision. +@end ftable + +@node Other I/O Functions, , Binary I/O, C-Style I/O Functions +@subsection Other I/O Functions + +@findex fgets +@example +fgets (@var{file}, len) +@end example +Read @samp{len} characters from a file. + +To flush output to a stream, use the function @code{fflush (@var{file})}. +This is useful for ensuring that all pending output makes it to the +screen before some other event occurs. For example, it is always a good +idea to flush the standard output stream before calling @code{input}. + +Three functions are available for setting and determining the position of +the file pointer for a given file. + +@findex ftell +The position of the file pointer (as the number of characters from the +beginning of the file) can be obtained using the the function +@code{ftell (@var{file})}. + +@findex fseek +To set the file pointer to any location within the file, use the +function @code{fseek (@var{file}, offset, origin)}. The pointer is placed +@code{offset} characters from the @code{origin}, which may be one of the +predefined variables @code{SEEK_CUR} (current position), @code{SEEK_SET} +(beginning), or @code{SEEK_END} (end of file). If @code{origin} is +omitted, @code{SEEK_SET} is assumed. The offset must be zero, or a +value returned by @code{ftell} (in which case @code{origin} must be +@code{SEEK_SET}. @xref{Predefined Constants}. + +@findex frewind +The function @code{frewind (@var{file})} moves the file pointer to the +beginning of a file, returning 1 for success, and 0 if an error was +encountered. It is equivalent to @code{fseek (@var{file}, 0, SEEK_SET)}. + +The following example stores the current file position in the variable +@samp{marker}, moves the pointer to the beginning of the file, reads +four characters, and then returns to the original position. + +@example +marker = ftell (myfile); +frewind (myfile); +fourch = fgets (myfile, 4); +fseek (myfile, marker, SEEK_SET); +@end example + +@findex feof +The function @code{feof (@var{file})} allows you to find out if an +end-of-file condition has been encountered for a given file. Note that +it will only return 1 if the end of the file has already been +encountered, not if the next read operation will result in an +end-of-file condition. + +@findex ferror +Similarly, the function @code{ferror (@var{file})} allows you to find +out if an error condition has been encountered for a given file. Note +that it will only return 1 if an error has already been encountered, not +if the next operation will result in an error condition. + +@findex kbhit +The function @code{kbhit} may be usd to read a single keystroke from the +keyboard. For example, + +@example +x = kbhit (); +@end example + +@noindent +will set @var{x} to the next character typed at the keyboard, without +requiring a carriage return to be typed. + +@findex freport +Finally, it is often useful to know exactly which files have been +opened, and whether they are open for reading, writing, or both. The +command @code{freport} prints this information for all open files. For +example, + +@example +@group +octave:13> freport + + number mode name + + 0 r stdin + 1 w stdout + 2 w stderr + 3 r myfile +@end group +@end example
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/linalg.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,786 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Linear Algebra, Polynomial Manipulations, Arithmetic, Top +@chapter Linear Algebra + +This chapter documents the linear algebra functions of Octave. +Reference material for many of these options may be found in +Golub and Van Loan, @cite{Matrix Computations, 2nd Ed.}, Johns Hopkins, +1989, and in @cite{LAPACK Users' Guide}, SIAM, 1992. + +@menu +* Basic Matrix Functions:: +* Matrix Factorizations:: +* Functions of a Matrix:: +@end menu + +@node Basic Matrix Functions, Matrix Factorizations, Linear Algebra, Linear Algebra +@section Basic Matrix Functions + +@ftable @code +@item balance + +@example +aa = balance (a, opt) +[dd, aa] = balance(a, opt) +[dd, aa] = balance (a, opt) +[cc, dd, aa, bb] = balance (a, b, opt) +@end example + +@code{[dd, aa] = balance (a)} returns @code{aa = dd \ a * dd}. +@code{aa} is a matrix whose row/column norms are roughly equal in +magnitude, and @code{dd} = @code{p * d}, where @code{p} is a permutation +matrix and @code{d} is a diagonal matrix of powers of two. This allows +the equilibration to be computed without roundoff. Results of +eigenvalue calculation are typically improved by balancing first. + +@code{[cc, dd, aa, bb] = balance (a, b)} returns @code{aa} (@code{bb}) +@code{= cc*a*dd (cc*b*dd)}), where @code{aa} and @code{bb} have +non-zero elements of approximately the same magnitude and @code{cc} +and @code{dd} are permuted diagonal matrices as in @code{dd} for +the algebraic eigenvalue problem. + +The eigenvalue balancing option @code{opt} is selected as follows: + +@table @asis +@item @code{"N"}, @code{"n"} +No balancing; arguments copied, transformation(s) set to identity. + +@item @code{"P"}, @code{"p"} +Permute argument(s) to isolate eigenvalues where possible. + +@item @code{"S"}, @code{"s"} +Scale to improve accuracy of computed eigenvalues. + +@item @code{"B"}, @code{"b"} +Permute and scale, in that order. Rows/columns of a (and b) +that are isolated by permutation are not scaled. This is the default +behavior. +@end table + +Algebraic eigenvalue balancing uses standard LAPACK routines. + +Generalized eigenvalue problem balancing uses Ward's algorithm +(SIAM Journal on Scientific and Statistical Computing, 1981). + +@item cond (@var{a}) +Compute the (two-norm) condition number of a matrix. @code{cond (a)} is +defined as @code{norm (a) * norm (inv (a))}, and is computed via a +singular value decomposition. + +@item det (@var{a}) +Compute the determinant of @var{a} using LINPACK. + +@item eig + +@example + = eig (a) +[v, lambda] = eig (a) +@end example + +The eigenvalues (and eigenvectors) of a matrix are computed in a several +step process which begins with a Hessenberg decomposition (see +@code{hess}), followed by a Schur decomposition (see @code{schur}), from +which the eigenvalues are apparent. The eigenvectors, when desired, are +computed by further manipulations of the Schur decomposition. + +See also: @code{hess}, @code{schur}. + +@item givens + +@example +[c, s] = givens (x, y) +G = givens (x, y) +@end example + +@code{G = givens(x, y)} returns a +@iftex +@tex +$2\times 2$ +@end tex +@end iftex +@ifinfo +2 x 2 +@end ifinfo +orthogonal matrix @code{G = [c s; -s' c]} such that +@code{G [x; y] = [*; 0]} (x, y scalars) + +@item inv (@var{a}) +@itemx inverse (@var{a}) +Compute the inverse of the square matrix @var{a}. + +@item norm (@var{a}, @var{p}) +Compute the p-norm of the matrix @var{a}. If the second argument is +missing, @code{p = 2} is assumed. + +If @var{a} is a matrix: + +@table @asis +@item @var{p} = @code{1} +1-norm, the largest column sum of @var{a}. + +@item @var{p} = @code{2} +Largest singular value of @var{a}. + +@item @var{p} = @code{Inf} +Infinity norm, the largest row sum of @var{a}. + +@item @var{p} = @code{"fro"} +Frobenius norm of @var{a}, @code{sqrt (sum (diag (a' * a)))}. +@end table + +If @var{a} is a vector or a scalar: + +@table @asis +@item @var{p} = @code{Inf} +@code{max (abs (a))}. + +@item @var{p} = @code{-Inf} +@code{min (abs (a))}. + +@item other +p-norm of @var{a}, @code{(sum (abs (a) .^ p)) ^ (1/p)}. +@end table + +@item null (@var{a}, @var{tol}) +Returns an orthonormal basis of the null space of @var{a}. + +The dimension of the null space is taken as the number of singular +values of @var{a} not greater than @var{tol}. If the argument @var{tol} +is missing, it is computed as + +@example +max (size (a)) * max (svd (a)) * eps +@end example + +@item orth (@var{a}, @var{tol}) +Returns an orthonormal basis of the range of @var{a}. + +The dimension of the range space is taken as the number of singular +values of @var{a} greater than @var{tol}. If the argument @var{tol} is +missing, it is computed as + +@example +max (size (a)) * max (svd (a)) * eps +@end example + +@item pinv (@var{X}, @var{tol}) +Returns the pseudoinverse of @var{X}. Singular values less than +@var{tol} are ignored. + +If the second argument is omitted, it is assumed that + +@example +tol = max (size (X)) * sigma_max (X) * eps, +@end example + +@noindent +where @code{sigma_max (@var{X})} is the maximal singular value of @var{X}. + +@item rank (@var{a}, @var{tol}) +Compute the rank of @var{a}, using the singular value decomposition. +The rank is taken to be the number of singular values of @var{a} that +are greater than the specified tolerance @var{tol}. If the second +argument is omitted, it is taken to be + +@example +tol = max (size (a)) * sigma (1) * eps; +@end example + +@noindent +where @code{eps} is machine precision and @code{sigma} is the largest +singular value of @code{a}. + +@item trace (@var{a}) +Compute the trace of @var{a}, @code{sum (diag (a))}. + +@end ftable + +@node Matrix Factorizations, Functions of a Matrix, Basic Matrix Functions, Linear Algebra +@section Matrix Factorizations + +@ftable @code +@item chol (@var{a}) +Compute the Cholesky factor, @var{r}, of the symmetric positive definite +matrix @var{a}, where +@iftex +@tex +$ R^T R = A $. +@end tex +@end iftex +@ifinfo + +@example +r' * r = a. +@end example +@end ifinfo + +@item hess (@var{a}) +Compute the Hessenberg decomposition of the matrix @var{a}. + +@example + h = hess (a) +[p, h] = hess (a) +@end example + +The Hessenberg decomposition is usually used as the first step in an +eigenvalue computation, but has other applications as well (see Golub, +Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979. The +Hessenberg decomposition is @code{p * h * p' = a} where @code{p} is a +square unitary matrix (@code{p' * p = I}, using complex-conjugate +transposition) and @code{h} is upper Hessenberg +(@code{i >= j+1 => h (i, j) = 0}). + +@item lu (@var{a}) +Compute the LU decomposition of @var{a}, using subroutines from +LAPACK. The result is returned in a permuted form, according to +the optional return value @var{p}. For example, given the matrix +@code{a = [1, 2; 3, 4]}, + +@example +[l, u, p] = lu (a) +@end example + +@noindent +returns + +@example +l = + + 1.00000 0.00000 + 0.33333 1.00000 + +u = + + 3.00000 4.00000 + 0.00000 0.66667 + +p = + + 0 1 + 1 0 +@end example + +@item qr (@var{a}) +Compute the QR factorization of @var{a}, using standard LAPACK +subroutines. For example, given the matrix @code{a = [1, 2; 3, 4]}, + +@example +[q, r] = qr (a) +@end example + +@noindent +returns + +@example +q = + + -0.31623 -0.94868 + -0.94868 0.31623 + +r = + + -3.16228 -4.42719 + 0.00000 -0.63246 +@end example + +The @code{qr} factorization has applications in the solution of least +squares problems +@iftex +@tex +$$ +\min_x \left\Vert A x - b \right\Vert_2 +$$ +@end tex +@end iftex +@ifinfo + +@example +@code{min norm(A x - b)} +@end example + +@end ifinfo +for overdetermined systems of equations (i.e., +@iftex +@tex +$A$ +@end tex +@end iftex +@ifinfo +@code{a} +@end ifinfo + is a tall, thin matrix). The @code{qr} factorization is @code{q * r = a} +where @code{q} is an orthogonal matrix and @code{r} is upper triangular. + +The permuted @code{qr} factorization @code{[q, r, pi] = qr (a)} forms +the @code{qr} factorization such that the diagonal entries of @code{r} +are decreasing in magnitude order. For example, given the matrix +@code{a = [1, 2; 3, 4]}, + +@example +[q, r, pi] = qr(a) +@end example + +@noindent +returns + +@example +q = + + -0.44721 -0.89443 + -0.89443 0.44721 + +r = + + -4.47214 -3.13050 + 0.00000 0.44721 + +p = + + 0 1 + 1 0 +@end example + +The permuted @code{qr} factorization @code{[q, r, pi] = qr (a)} +factorization allows the construction of an orthogonal basis of +@code{span (a)}. + +@item schur + +@example +[u, s] = schur (a, opt) opt = "a", "d", or "u" + s = schur (a) +@end example + +The Schur decomposition is used to compute eigenvalues of a +square matrix, and has applications in the solution of algebraic +Riccati equations in control (see @code{are} and @code{dare}). +@code{schur} always returns +@iftex +@tex +$S = U^T A U$ +@end tex +@end iftex +@ifinfo +@code{s = u' * a * u} +@end ifinfo +where +@iftex +@tex +$U$ +@end tex +@end iftex +@ifinfo +@code{u} +@end ifinfo + is a unitary matrix +@iftex +@tex +($U' U$ +@end tex +@end iftex +@ifinfo +(@code{u'* u} +@end ifinfo + is identity) +and +@iftex +@tex +$S$ +@end tex +@end iftex +@ifinfo +@code{s} +@end ifinfo +is upper triangular. The eigenvalues of +@iftex +@tex +$A$ (and $S$) +@end tex +@end iftex +@ifinfo +@code{a} (and @code{s}) +@end ifinfo +are the diagonal elements of +@iftex +@tex +$S$ +@end tex +@end iftex +@ifinfo +@code{s} +@end ifinfo +If the matrix +@iftex +@tex +$A$ +@end tex +@end iftex +@ifinfo +@code{a} +@end ifinfo +is real, then the real Schur decomposition is computed, in which the +matrix +@iftex +@tex +$U$ +@end tex +@end iftex +@ifinfo +@code{u} +@end ifinfo +is orthogonal and +@iftex +@tex +$S$ +@end tex +@end iftex +@ifinfo +@code{s} +@end ifinfo +is block upper triangular +with blocks of size at most +@iftex +@tex +$2\times 2$ +@end tex +@end iftex +@ifinfo +@code{2 x 2} +@end ifinfo +blocks along the diagonal. The diagonal elements of +@iftex +@tex +$S$ +@end tex +@end iftex +@ifinfo +@code{s} +@end ifinfo +(or the eigenvalues of the +@iftex +@tex +$2\times 2$ +@end tex +@end iftex +@ifinfo +@code{2 x 2} +@end ifinfo +blocks, when +appropriate) are the eigenvalues of +@iftex +@tex +$A$ +@end tex +@end iftex +@ifinfo +@code{a} +@end ifinfo +and +@iftex +@tex +$S$. +@end tex +@end iftex +@ifinfo +@code{s}. +@end ifinfo + +The eigenvalues are optionally ordered along the diagonal according to +the value of @code{opt}. @code{opt = "a"} indicates that all +eigenvalues with negative real parts should be moved to the leading +block of +@iftex +@tex +$S$ +@end tex +@end iftex +@ifinfo +@code{s} +@end ifinfo +(used in @code{are}), @code{opt = "d"} indicates that all eigenvalues +with magnitude less than one should be moved to the leading block of +@iftex +@tex +$S$ +@end tex +@end iftex +@ifinfo +@code{s} +@end ifinfo +(used in @code{dare}), and @code{opt = "u"}, the default, indicates that +no ordering of eigenvalues should occur. The leading +@iftex +@tex +$k$ +@end tex +@end iftex +@ifinfo +@code{k} +@end ifinfo +columns of +@iftex +@tex +$U$ +@end tex +@end iftex +@ifinfo +@code{u} +@end ifinfo +always span the +@iftex +@tex +$A$-invariant +@end tex +@end iftex +@ifinfo +@code{a}-invariant +@end ifinfo +subspace corresponding to the +@iftex +@tex +$k$ +@end tex +@end iftex +@ifinfo +@code{k} +@end ifinfo +leading eigenvalues of +@iftex +@tex +$S$. +@end tex +@end iftex +@ifinfo +@code{s}. +@end ifinfo + +@item svd (@var{a}) +Compute the singular value decomposition of @var{a} +@iftex +@tex +$$ + A = U\Sigma V^H +$$ +@end tex +@end iftex +@ifinfo + +@example +a = u * sigma * v' +@end example +@end ifinfo + +The function @code{svd} normally returns the vector of singular values. +If asked for three return values, it computes +@iftex +@tex +$U$, $S$, and $V$. +@end tex +@end iftex +@ifinfo +U, S, and V. +@end ifinfo +For example, + +@example +svd (hilb (3)) +@end example + +@noindent +returns + +@example +ans = + + 1.4083189 + 0.1223271 + 0.0026873 +@end example + +@noindent +and + +@example +[u, s, v] = svd (hilb (3)) +@end example + +@noindent +returns + +@example +u = + + -0.82704 0.54745 0.12766 + -0.45986 -0.52829 -0.71375 + -0.32330 -0.64901 0.68867 + +s = + + 1.40832 0.00000 0.00000 + 0.00000 0.12233 0.00000 + 0.00000 0.00000 0.00269 + +v = + + -0.82704 0.54745 0.12766 + -0.45986 -0.52829 -0.71375 + -0.32330 -0.64901 0.68867 +@end example + +If given a second argument, @code{svd} returns an economy-sized +decomposition, eliminating the unnecessary rows or columns of @var{u} or +@var{v}. +@end ftable + +@node Functions of a Matrix, , Matrix Factorizations, Linear Algebra +@section Functions of a Matrix + +@ftable @code +@item expm + +@example +expm (a) +@end example + +Returns the exponential of a matrix, defined as the +infinite Taylor series +@iftex +@tex +$$ + \exp (A) = I + A + {A^2 \over 2!} + {A^3 \over 3!} + \cdots +$$ +@end tex +@end iftex +@ifinfo + +@example +expm(a) = I + a + a^2/2! + a^3/3! + ... +@end example + +@end ifinfo +The Taylor series is @emph{not} the way to compute the matrix +exponential; see Moler and Van Loan, @cite{Nineteen Dubious Ways to +Compute the Exponential of a Matrix}, SIAM Review, 1978. This routine +uses Ward's diagonal +@iftex +@tex +Pad\'e +@end tex +@end iftex +@ifinfo +Pade' +@end ifinfo +approximation method with +three step preconditioning (SIAM Journal on Numerical Analysis, 1977). + +Diagonal +@iftex +@tex +Pad\'e +@end tex +@end iftex +@ifinfo +Pade' +@end ifinfo + approximations are rational polynomials of matrices +@iftex +@tex +$D_q(a)^{-1}N_q(a)$ +@end tex +@end iftex +@ifinfo + +@example + -1 +D (a) N (a) +@end example + +@end ifinfo + whose Taylor series matches the first +@iftex +@tex +$2 q + 1 $ +@end tex +@end iftex +@ifinfo +@code{2q+1} +@end ifinfo +terms of the Taylor series above; direct evaluation of the Taylor series +(with the same preconditioning steps) may be desirable in lieu of the +@iftex +@tex +Pad\'e +@end tex +@end iftex +@ifinfo +Pade' +@end ifinfo +approximation when +@iftex +@tex +$D_q(a)$ +@end tex +@end iftex +@ifinfo +@code{Dq(a)} +@end ifinfo +is ill-conditioned. + +@item logm (@var{a}) +Compute the matrix logarithm of the square matrix @var{a}. Note that +this is currently implemented in terms of an eigenvalue expansion and +needs to be improved to be more robust. + +@item sqrtm (@var{a}) +Compute the matrix square root of the square matrix @var{a}. Note that +this is currently implemented in terms of an eigenvalue expansion and +needs to be improved to be more robust. + +@item kron (@var{a}, @var{b}) + +Form the kronecker product of two matrices, defined block by block as + +@example +x = [a(i, j) b] +@end example + +@item qzhess (@var{a}, @var{b}) +Compute the Hessenberg-triangular decomposition of the matrix pencil +@code{(a, b)}. This function returns @code{aa = q * a * z}, +@code{bb = q * b * z}, @code{q}, @code{z} orthogonal. For example, + +@example +[aa, bb, q, z] = qzhess (a, b) +@end example + +The Hessenberg-triangular decomposition is the first step in +Moler and Stewart's QZ decomposition algorithm. (The QZ decomposition +will be included in a later release of Octave.) + +Algorithm taken from Golub and Van Loan, @cite{Matrix Computations, 2nd +edition}. + +@item qzval (@var{a}, @var{b}) +Compute generalized eigenvalues. + +@item syl (@var{a}, @var{b}, @var{c}) +Solve the Sylvester equation +@iftex +@tex +$$ + A X + X B + C = 0 +$$ +@end tex +@end iftex +@ifinfo + +@example +A X + X B + C = 0 +@end example + +@end ifinfo +using standard LAPACK subroutines. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/lp-foo.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,35 @@ +@c ------------------------------------------------------------------------ + +@node Linear Programming, Quadratic Programming, Quadrature, Top +@chapter Linear Programming +@cindex LP +@cindex linear programming + +@example +class LP + LP (void) + LP (const ColumnVector& c) + LP (const ColumnVector& c, const Bounds& b) + LP (const ColumnVector& c, const Bounds& b, const LinConst& lc) + LP (const ColumnVector& c, const LinConst& lc) + + virtual ColumnVector minimize (void) + virtual ColumnVector minimize (double& objf) + virtual ColumnVector minimize (double& objf, int& inform) + virtual ColumnVector minimize (double& objf, int& inform, ColumnVector& lambda) = 0 + +class LPsolve : public LP + LPsolve (void) : LP () + + LPsolve (const ColumnVector& c) : LP (c) + + LPsolve (const ColumnVector& c, const Bounds& b) : LP (c, b) + + LPsolve (const ColumnVector& c, const Bounds& b, const LinConst& lc) + : LP (c, b, lc) + + LPsolve (const ColumnVector& c, const LinConst& lc) : LP (c, lc) + + virtual ColumnVector minimize (double& objf, int& inform, ColumnVector& lambda) +@end example +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/matrix.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,335 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Matrix Manipulation, String Functions, Special Matrices, Top +@chapter Matrix Manipulation + +There are a number of functions available for checking to see if the +elements of a matrix meet some condition, and for rearranging the +elements of a matrix. For example, Octave can easily tell you if all +the elements of a matrix are finite, or are less than some specified +value. Octave can also rotate the elements, extract the upper- or +lower-triangular parts, or sort the columns of a matrix. + +@menu +* Finding Elements and Checking Conditions:: +* Rearranging Matrices:: +@end menu + +@node Finding Elements and Checking Conditions, Rearranging Matrices, Matrix Manipulation, Matrix Manipulation +@section Finding Elements and Checking Conditions + +@findex any +@findex all + +The functions @code{any} and @code{all} are useful for determining +whether any or all of the elements of a matrix satisfy some condition. +The @code{find} function is also useful in determining which elements of +a matrix meet a specified condition. + +Given a vector, the function @code{any} returns 1 if any element of the +vector is nonzero. + +For a matrix argument, @code{any} returns a row vector of ones and +zeros with each element indicating whether any of the elements of the +corresponding column of the matrix are nonzero. For example, + +@example +octave:13> any (eye (2, 4)) +ans = + + 1 1 0 0 +@end example + +To see if any of the elements of a matrix are nonzero, you can use a +statement like + +@example +any (any (a)) +@end example + +The function @code{all} behaves like the function @code{any}, except +that it returns true only if all the elements of a vector, or all the +elements in a column of a matrix, are nonzero. + +Since the comparison operators (@pxref{Comparison Ops}) return matrices +of ones and zeros, it is easy to test a matrix for many things, not just +whether the elements are nonzero. For example, + +@example +octave:13> all (all (rand (5) < 0.9)) +ans = 0 +@end example + +@noindent +tests a random 5 by 5 matrix to see if all of it's elements are less +than 0.9. + +Note that in conditional contexts (like the test clause of @code{if} and +@code{while} statements) Octave treats the test as if you had typed +@code{all (all (condition))}. + +@findex isinf +@findex finite +@findex isnan + +The functions @code{isinf}, @code{finite}, and @code{isnan} return 1 if +their arguments are infinite, finite, or not a number, respectively, and +return 0 otherwise. For matrix values, they all work on an element by +element basis. For example, evaluating the expression + +@example +isinf ([1, 2; Inf, 4]) +@end example + +@noindent +produces the matrix + +@example +ans = + + 0 0 + 1 0 +@end example + +@findex find + +The function @code{find} returns a vector of indices of nonzero elements +of a matrix. To obtain a single index for each matrix element, Octave +pretends that the columns of a matrix form one long vector (like Fortran +arrays are stored). For example, + +@example +octave:13> find (eye (2)) +ans = + + 1 + 4 +@end example + +If two outputs are requested, @code{find} returns the row and column +indices of nonzero elements of a matrix. For example, + +@example +octave:13> [i, j] = find (eye (2)) +i = + + 1 + 2 + +j = + + 1 + 2 +@end example + +If three outputs are requested, @code{find} also returns the nonzero +values in a vector. + +@node Rearranging Matrices, , Finding Elements and Checking Conditions, Matrix Manipulation +@section Rearranging Matrices + +@findex fliplr +@findex flipud + +The function @code{fliplr} reverses the order of the columns in a +matrix, and @code{flipud} reverses the order of the rows. For example, + +@example +octave:13> fliplr ([1, 2; 3, 4]) +ans = + + 2 1 + 4 3 + +octave:13> flipud ([1, 2; 3, 4]) +ans = + + 3 4 + 1 2 +@end example + +@findex rot90 + +The function @code{rot90 (@var{a}, @var{n})} rotates a matrix +counterclockwise in 90-degree increments. The second argument is +optional, and specifies how many 90-degree rotations are to be applied +(the default value is 1). Negative values of @var{n} rotate the matrix +in a clockwise direction. For example, + +@example +rot90 ([1, 2; 3, 4], -1) +ans = + + 3 1 + 4 2 +@end example + +@noindent +rotates the given matrix clockwise by 90 degrees. The following are all +equivalent statements: + +@example +rot90 ([1, 2; 3, 4], -1) +rot90 ([1, 2; 3, 4], 3) +rot90 ([1, 2; 3, 4], 7) +@end example + +@findex reshape + +The function @code{reshape (@var{a}, @var{m}, @var{n})} returns a matrix +with @var{m} rows and @var{n} columns whose elements are taken from the +matrix @var{a}. To decide how to order the elements, Octave pretends +that the elements of a matrix are stored in column-major order (like +Fortran arrays are stored). + +For example, + +@example +octave:13> reshape ([1, 2, 3, 4], 2, 2) +ans = + + 1 3 + 2 4 +@end example + +If the variable @code{do_fortran_indexing} is @code{"true"}, the +@code{reshape} function is equivalent to + +@example +retval = zeros (m, n); +retval (:) = a; +@end example + +@noindent +but it is somewhat less cryptic to use @code{reshape} instead of the +colon operator. Note that the total number of elements in the original +matrix must match the total number of elements in the new matrix. + +@findex sort + +The function @samp{sort} can be used to arrange the elements of a vector +in increasing order. For matrices, @code{sort} orders the elements in +each column. + +For example, + +@example +octave:13> sort (rand (4)) +ans = + + 0.065359 0.039391 0.376076 0.384298 + 0.111486 0.140872 0.418035 0.824459 + 0.269991 0.274446 0.421374 0.938918 + 0.580030 0.975784 0.562145 0.954964 +@end example + +The @code{sort} function may also be used to produce a matrix +containing the original row indices of the elements in the sorted +matrix. For example, + +@example +s = + + 0.051724 0.485904 0.253614 0.348008 + 0.391608 0.526686 0.536952 0.600317 + 0.733534 0.545522 0.691719 0.636974 + 0.986353 0.976130 0.868598 0.713884 + +i = + + 2 4 2 3 + 4 1 3 4 + 1 2 4 1 + 3 3 1 2 +@end example + +@noindent +These values may be used to recover the original matrix from the sorted +version. For example, + +@example +@end example + +The @code{sort} function does not allow sort keys to be specified, so it +can't be used to order the rows of a matrix according to the values of +the elements in various columns@footnote{For example, to first sort +based on the values in column 1, and then, for any values that are +repeated in column 1, sort based on the values found in column 2, etc.} +in a single call. Using the second output, however, it is possible to +sort all rows based on the values in a given column. Here's an example +that sorts the rows of a matrix based on the values in the third column. + +@example +octave:13> a = rand (4) +a = + + 0.080606 0.453558 0.835597 0.437013 + 0.277233 0.625541 0.447317 0.952203 + 0.569785 0.528797 0.319433 0.747698 + 0.385467 0.124427 0.883673 0.226632 + +octave:14> [s, i] = sort (a (:, 3)); +octave:15> a (i, :) +ans = + + 0.569785 0.528797 0.319433 0.747698 + 0.277233 0.625541 0.447317 0.952203 + 0.080606 0.453558 0.835597 0.437013 + 0.385467 0.124427 0.883673 0.226632 +@end example + +@findex triu +@findex tril + +The functions @code{triu (@var{a}, @var{k})} and @code{tril (@var{a}, +@var{k})} extract the upper or lower triangular part of the matrix +@var{a}, and set all other elements to zero. The second argument is +optional, and specifies how many diagonals above or below the main +diagonal should also be set to zero. + +The default value of @var{k} is zero, so that @code{triu} and +@code{tril} normally include the main diagonal as part of the result +matrix. + +If the value of @var{k} is negative, additional elements above (for +@code{tril}) or below (for @code{triu}) the main diagonal are also +selected. + +The absolute value of @var{k} must not be greater than the number of +sub- or super-diagonals. + +For example, + +@example +@group +octave:13> tril (rand (4), -1) +ans = + + 0.00000 0.00000 0.00000 0.00000 + 0.09012 0.00000 0.00000 0.00000 + 0.01215 0.34768 0.00000 0.00000 + 0.00302 0.69518 0.91940 0.00000 +@end group +@end example + +@noindent +forms a lower triangular matrix from a random 4 by 4 matrix, omitting +the main diagonal, and + +@example +@group +octave:13> tril (rand (4), 1) +ans = + + 0.06170 0.51396 0.00000 0.00000 + 0.96199 0.11986 0.35714 0.00000 + 0.16185 0.61442 0.79343 0.52029 + 0.68016 0.48835 0.63609 0.72113 +@end group +@end example + +@noindent +forms a lower triangular matrix from a random 4 by 4 matrix, including +the main diagonal and the first super-diagonal.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/nonlin.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,99 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Nonlinear Equations, Differential Equations, Polynomial Manipulations, Top +@chapter Nonlinear Equations +@cindex nonlinear equations +@cindex equations, nonlinear + +@findex fsolve + +Octave can solve sets of nonlinear equations of the form +@iftex +@tex +$$ + f (x) = 0 +$$ +@end tex +@end iftex +@ifinfo + +@example +F (x) = 0 +@end example +@end ifinfo + +@noindent +using the function @code{fsolve}, which is based on the MINPACK +subroutine @code{hybrd}. + +For example, to solve the set of equations +@iftex +@tex +$$ + \eqalign{-2x^2 + 3xy + 4\sin(y) - 6 &= 0\cr + 3x^2 - 2xy^2 + 3\cos(x) + 4 &= 0} +$$ +@end tex +@end iftex +@ifinfo + +@example +-2x^2 + 3xy + 4 sin(y) = 6 + 3x^2 - 2xy^2 + 3 cos(x) = -4 +@end example +@end ifinfo + +@noindent +you first need to write a function to compute the value of the given +function. For example: + +@example +function y = f (x) + + y(1) = -2*x(1)^2 + 3*x(1)*x(2) + 4*sin(x(2)) - 6; + y(2) = 3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4; + +endfunction +@end example + +Then, call @code{fsolve} with a specified initial condition to find the +roots of the system of equations. For example, given the function +@code{f} defined above, + +@example +[x, info] = fsolve ("f", [1; 2]) +@end example + +@noindent +results in the solution + +@example +x = + + 0.57983 + 2.54621 + +info = 1 +@end example + +A value of @code{info = 1} indicates that the solution has converged. + +The function @code{perror} may be used to print English messages +corresponding to the numeric error codes. For example, + +@example +perror ("fsolve", 1) +@end example + +@noindent +prints + +@example +solution converged to requested tolerance +@end example + +@findex fsolve_options +Tolerances and other options for @code{fsolve} may be specified using the +function @code{fsolve_options}.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/octave.1 Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,82 @@ +.\" Man page for Octave +.\" +.\" Copyright (C) 1996 John W. Eaton +.\" +.\" This file is part of Octave. +.\" +.\" Octave is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License as published by the +.\" Free Software Foundation; either version 2, or (at your option) any +.\" later version. +.\" +.\" Octave is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with Octave; see the file COPYING. If not, write to the Free +.\" Software Foundation, 59 Temple Place - Suite 330, Boston, MA +.\" 02111-1307, USA. +.\" +.TH Octave 1 "Jan 8 1996" +.LO 1 +.SH NAME +Octave \- A high-level interactive language for numerical computations. +.SH SYNOPSIS +.nf +octave [options] +.fi +.SH OPTIONS +The complete set of command-line options for octave is available by +running the command +.nf + + octave --help + +.fi +.SH DESCRIPTION +Octave is a high-level language, primarily intended for numerical +computations. It provides a convenient command line interface for +solving linear and nonlinear problems numerically. +.SH DOCUMENTATION +The primary documentation for Octave is written using Texinfo, the GNU +documentation system, which allows the same source files to be used to +produce on-line and printed versions of the manual. +.PP +You can read the on-line copy of the Octave documentation by issuing +the command +.nf + + octave:13> help -i + +.fi +while running Octave interactively, by using the GNU Emacs info mode, +or by running standalone programs like info or xinfo. +.SH BUGS +The best way to submit a bug report for Octave is to use the command +.nf + + octave:13> bug_report + +.fi +while running Octave interactively. This will create a template bug +report file and start an editor on that file. Your +message will be sent to the bug-octave mailing list +once you are finished editing the template. +.PP +If you are unable to use the bug_report command, send your message +to the +.B bug-octave@bevo.che.wisc.edu +mailing list by some other means. Please read the `Bugs' chapter in +the Octave manual to find out how to submit a bug report that will +enable the Octave maintainers to fix the problem. +.SH AUTHOR +.nf +John W. Eaton +Department of Chemical Engineering +University of Wisconsin-Madison +Madison, WI 53706 +USA +<jwe@bevo.che.wisc.edu> +.fi
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/octave.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,480 @@ +% Copyright (C) 1996 John W. Eaton +% This is part of the Octave manual. +% For copying conditions, see the file gpl.texi. + +\input texinfo +@setfilename octave.info + +@c Settings for printing on 8-1/2 by 11 inch paper: +@c ----------------------------------------------- + +@setchapternewpage odd +@iftex +@tex +\global\chapheadingskip = 15pt plus 4pt minus 2pt +\global\secheadingskip = 12pt plus 3pt minus 2pt +\global\subsecheadingskip = 9pt plus 2pt minus 2pt +\global\parskip 5pt plus 1pt +@end tex +@end iftex + +@c Settings for small book format: +@c ------------------------------ +@c +@c @smallbook +@c @setchapternewpage odd +@c @finalout +@c @iftex +@c @cropmarks +@c @end iftex + +@defindex op + +@c Things like the Octave version number are defined in conf.texi. +@c This file doesn't include a chapter, so it must not be included +@c if you want to run the Emacs function texinfo-multiple-files-update. + +@include conf.texi + +@settitle Octave + +@ifinfo + +Copyright (C) 1996 John W. Eaton. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of +a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for +modified versions. +@end ifinfo + +@titlepage +@title{Octave} +@subtitle{A high-level interactive language for numerical computations} +@subtitle{Edition 1.1 for Octave version @value{VERSION}} +@subtitle{January 1995} +@author{John W. Eaton} +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1996 John W. Eaton. + +This is the first edition of the Octave documentation, +and is consistent with version @value{VERSION} of Octave. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the same conditions as for modified versions. +@end titlepage + +@ifinfo +@node Top, Preface, (dir), (dir) +@top + +This manual documents how to run, install and port Octave, as well as +its new features and incompatibilities, and how to report bugs. +It corresponds to Octave version @value{VERSION}. +@end ifinfo + +@menu +* Preface:: +* Copying:: +* Introduction:: A brief introduction to Octave. +* Invoking Octave:: Command options supported by Octave. +* Expressions:: Expressions. +* Statements:: Looping and program flow control. +* Functions and Scripts:: +* Built-in Variables:: Descriptions of all built-in variables. +* Arithmetic:: +* Linear Algebra:: +* Polynomial Manipulations:: +* Nonlinear Equations:: +* Differential Equations:: +* Optimization:: +* Quadrature:: +* Control Theory:: +* Signal Processing:: +* Sets:: +* Statistics:: +* Plotting:: +* Image Processing:: +* Audio Processing:: +* Input and Output:: +* Special Matrices:: +* Matrix Manipulation:: +* String Functions:: +* System Utilities:: +* Command History Functions:: +* Help:: +* Programming Utilities:: +* Amusements:: +* Emacs:: +* Installation:: How to configure, compile and install Octave. +* Trouble:: If you have trouble installing Octave. +* Command Line Editing:: Command history and editing. +* Using Info:: +* Concept Index:: An item for each concept. +* Variable Index:: An item for each documented variable. +* Function Index:: An item for each documented function. +* Operator Index:: An item for each documented operator. +* Readline Index:: An index for readline commands. +* Info Index:: An index for info commands. + + --- The Detailed Node Listing --- + +A Brief Introduction to Octave + +* Running Octave:: +* Simple Examples:: +* Executable Octave Programs:: +* Comments:: +* Errors:: + +Invoking Octave + +* Command Line Options:: +* Startup Files:: + +Expressions + +* Constant Expressions:: +* Matrices:: +* Ranges:: +* Variables:: +* Index Expressions:: +* Data Structures:: +* Calling Functions:: +* Global Variables:: +* Keywords:: +* Arithmetic Ops:: +* Comparison Ops:: +* Boolean Expressions:: +* Assignment Ops:: +* Increment Ops:: +* Operator Precedence:: + +Constant Expressions + +* Numeric Constants:: +* String Constants:: + +Matrices + +* Empty Matrices:: + +Calling Functions + +* Call by Value:: +* Recursion:: + +Boolean Expressions + +* Element-by-element Boolean Operators:: +* Short-circuit Boolean Operators:: + +Statements + +* The if Statement:: +* The while Statement:: +* The for Statement:: +* The break Statement:: +* The continue Statement:: +* The unwind_protect Statement:: +* The try Statement:: +* Continuation Lines:: + +Functions and Script Files + +* Defining Functions:: +* Multiple Return Values:: +* Variable-length Argument Lists:: +* Variable-length Return Lists:: +* Returning From a Function:: +* Function Files:: +* Script Files:: +* Dynamically Linked Functions:: +* Organization of Functions:: + +Built-in Variables + +* Predefined Constants:: +* User Preferences:: +* Other Built-in Variables:: +* Summary of Preference Variables:: + +Arithmetic + +* Utility Functions:: +* Complex Arithmetic:: +* Trigonometry:: +* Sums and Products:: +* Special Functions:: + +Linear Algebra + +* Basic Matrix Functions:: +* Matrix Factorizations:: +* Functions of a Matrix:: + +Differential Equations + +* Ordinary Differential Equations:: +* Differential-Algebraic Equations:: + +Optimization + +* Quadratic Programming:: +* Nonlinear Programming:: +* Linear Least Squares:: + +Quadrature + +* Functions of one Variable:: +* Orthogonal Collocation:: + +Plotting + +* Two-Dimensional Plotting:: +* Three-Dimensional Plotting:: +* Miscellaneous Plotting Functions:: + +Input and Output + +* Basic Input and Output:: +* C-Style I/O Functions:: + +C-Style I/O Functions + +* Opening and Closing Files:: +* Formatted Output:: +* Output Conversion Syntax:: +* Table of Output Conversions:: +* Integer Conversions:: +* Floating-Point Conversions:: +* Other Output Conversions:: +* Formatted Input:: +* Input Conversion Syntax:: +* Table of Input Conversions:: +* Numeric Input Conversions:: +* String Input Conversions:: +* Binary I/O:: +* Other I/O Functions:: + +Special Matrices + +* Special Utility Matrices:: +* Famous Matrices:: + +Matrix Manipulation + +* Finding Elements and Checking Conditions:: +* Rearranging Matrices:: + +System Utilities + +* Timing Utilities:: +* Filesystem Utilities:: +* Interacting with the OS:: +* System Information:: +* Other Functions:: + +Programming Utilities + +* Evaluating Strings as Commands:: +* Miscellaneous Utilities:: + +Using Emacs With Octave + +* Setting Up Octave Mode:: +* Using Octave Mode:: +* GIM:: + +Installing Octave + +* Installation Problems:: +* Binary Distributions:: + +Binary Distributions + +* Installing Octave from a Binary Distribution:: +* Creating a Binary Distribution:: + +Known Causes of Trouble with Octave + +* Actual Bugs:: Bugs we will fix later. +* Reporting Bugs:: +* Bug Criteria:: +* Bug Lists:: +* Bug Reporting:: +* Sending Patches:: +* Service:: + +Reporting Bugs + +* Bug Criteria:: +* Where: Bug Lists. Where to send your bug report. +* Reporting: Bug Reporting. How to report a bug effectively. +* Patches: Sending Patches. How to send a patch for Octave. + +Command Line Editing + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Bare Essentials:: +* Readline Movement Commands:: +* Readline Killing Commands:: +* Readline Arguments:: +* Readline Init File:: Customizing Readline from a user's view. +* Readline Init Syntax:: +* Readline Vi Mode:: + +Readline Interaction + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. + +Readline Init File + +* Readline Init Syntax:: Syntax for the commands in @file{~/.inputrc}. +* Readline Vi Mode:: Switching to @code{vi} mode in Readline. + +Readline Init Syntax + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Miscellaneous Commands:: Other miscellaneous commands. + +Using Info + +* Cursor Commands:: +* Scrolling Commands:: +* Node Commands:: +* Searching Commands:: +* Xref Commands:: +* Window Commands:: +* Printing Nodes:: +* Other Info Commands:: +* Info Variables:: + +Using Info + +* Cursor Commands:: Commands which move the cursor within a node. +* Scrolling Commands:: Commands for moving the node around in a window. +* Node Commands:: Commands for selecting a new node. +* Searching Commands:: Commands for searching an info file. +* Xref Commands:: Commands for selecting cross references. +* Window Commands:: Commands which manipulate multiple windows. +* Printing Nodes:: How to print out the contents of a node. +* Other Info Commands:: A few commands that defy categories. +* Info Variables:: How to change the default behavior of Info. + +Selecting Cross References + +* Parts of an Xref:: What a cross reference is made of. +* Selecting Xrefs:: Commands for selecting menu or note items. + +Manipulating Multiple Windows + +* The Mode Line:: What appears in the mode line? +* Basic Windows:: Manipulating windows in Info. +* The Echo Area:: Used for displaying errors and reading input. +@end menu + +@include preface.texi +@include gpl.texi +@include intro.texi +@include invoke.texi +@include expr.texi +@include stmt.texi +@include func.texi +@include var.texi +@include arith.texi +@include linalg.texi +@include poly.texi +@include nonlin.texi +@include diffeq.texi +@include optim.texi +@include quad.texi +@include control.texi +@include signal.texi +@include set.texi +@include stats.texi +@include plot.texi +@include image.texi +@include audio.texi +@include io.texi +@include special.texi +@include matrix.texi +@include strings.texi +@include system.texi +@include history.texi +@include help.texi +@include program.texi +@include amuse.texi + +@c Appendices start here. Installation and bugs have to go before the +@c readline and Info appendices because we want to have separate indices +@c for them, and there appears to be no way to go back to the original +@c set of indices once a redirection has taken place. + +@include emacs.texi +@include install.texi +@include bugs.texi + +@c Make a separate index for all readline commands, functions, and +@c concepts. +@defindex rd +@syncodeindex cp rd +@syncodeindex fn rd +@syncodeindex ky rd +@syncodeindex vr rd + +@include rluser.texi + +@c Make a separate index for all Info commands, functions, and concepts. +@defindex in +@syncodeindex cp in +@syncodeindex fn in +@syncodeindex ky in +@syncodeindex vr in + +@include gnuinfo.texi + +@include cp-idx.texi +@include vr-idx.texi +@include fn-idx.texi +@include op-idx.texi +@include rd-idx.texi +@include in-idx.texi + +@contents + +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/op-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,8 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Operator Index, Readline Index, Function Index, Top +@unnumbered Operator Index + +@printindex op
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/optim.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,148 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Optimization, Quadrature, Differential Equations, Top +@chapter Optimization + +@menu +* Quadratic Programming:: +* Nonlinear Programming:: +* Linear Least Squares:: +@end menu + +@c @cindex linear programming +@cindex quadratic programming +@cindex nonlinear programming +@cindex optimization +@cindex LP +@cindex QP +@cindex NLP + +@node Quadratic Programming, Nonlinear Programming, Optimization, Optimization +@section Quadratic Programming + +@ftable @code +@item qpsol + +@example +[x, obj, info, lambda] + = qpsol (x, H, c, lb, ub, lb, A, ub) +@end example +Solve quadratic programs using Gill and Murray's QPSOL. Because QPSOL +is not freely redistributable, this function is only available if you +have obtained your own copy of QPSOL. @xref{Installation}. +@end ftable + +@findex qpsol_options +Tolerances and other options for @code{qpsol} may be specified using the +function @code{qpsol_options}. + +@node Nonlinear Programming, Linear Least Squares, Quadratic Programming, Optimization +@section Nonlinear Programming + +@ignore +@ftable @code +@item fsqp + +@example +fsqp () +@end example + +@findex fsqp_options +Tolerances and other options for @code{fsqp} may be specified using the +function @code{fsqp_options}. + +Sorry, this hasn't been implemented yet. +@end ignore + +@ftable @code +@item npsol + +@example +[x, obj, info, lambda] + = npsol (x, 'phi', lb, ub, lb, A, ub, lb, 'g', ub) +@end example +Solve nonlinear programs using Gill and Murray's NPSOL. Because NPSOL +is not freely redistributable, this function is only available if you +have obtained your own copy of NPSOL. @xref{Installation}. + +The second argument is a string containing the name of the objective +function to call. The objective function must be of the form + +@example +y = phi (x) +@end example + +@noindent +where x is a vector and y is a scalar. +@end ftable + +@findex npsol_options +Tolerances and other options for @code{npsol} may be specified using the +function @code{npsol_options}. + +@node Linear Least Squares, , Nonlinear Programming, Optimization +@section Linear Least Squares + +@ftable @code +@item gls (@var{Y}, @var{X}, @var{O}) +Generalized least squares (GLS) estimation for the multivariate model + +@example +Y = X * B + E, mean(E) = 0, cov(vec(E)) = (s^2)*O +@end example + +@noindent +with + +@example +Y an T x p matrix +X an T x k matrix +B an k x p matrix +E an T x p matrix +O an Tp x Tp matrix +@end example + +@noindent +Each row of Y and X is an observation and each column a variable. + +Returns BETA, v, and, R, where BETA is the GLS estimator for B, v is the +GLS estimator for s^2, and R = Y - X*BETA is the matrix of GLS residuals. + +@item ols (@var{Y}, @var{X}) +Ordinary Least Squares (OLS) estimation for the multivariate model + +@example +Y = X*B + E, mean (E) = 0, cov (vec (E)) = kron (S, I) +@end example + +@noindent +with + +@example +Y an T x p matrix +X an T x k matrix +B an k x p matrix +E an T x p matrix +@end example + +@noindent +Each row of Y and X is an observation and each column a variable. + +Returns BETA, SIGMA, and R, where BETA is the OLS estimator for B, i.e. + +@example +BETA = pinv(X)*Y, +@end example + +@noindent +where pinv(X) denotes the pseudoinverse of X, SIGMA is the OLS estimator +for the matrix S, i.e. + +@example +SIGMA = (Y - X*BETA)'*(Y - X*BETA) / (T - rank(X)) +@end example + +and R = Y - X*BETA is the matrix of OLS residuals. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/plot.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,569 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Plotting, Image Processing, Statistics, Top +@chapter Plotting + +@findex gplot +@findex gsplot + +All of Octave's plotting functions use @code{gnuplot} to handle the +actual graphics. There are two low-level functions, @code{gplot} and +@code{gsplot}, that behave almost exactly like the corresponding +@code{gnuplot} functions @code{plot} and @samp{splot}. A number of +other higher level plotting functions, patterned after the graphics +functions found in @sc{Matlab} version 3.5, are also available. +These higher level functions are all implemented in terms of the two +low-level plotting functions. + +@menu +* Two-Dimensional Plotting:: +* Three-Dimensional Plotting:: +* Miscellaneous Plotting Functions:: +@end menu + +@node Two-Dimensional Plotting, Three-Dimensional Plotting, Plotting, Plotting +@section Two-Dimensional Plotting + +The syntax for Octave's two-dimensional plotting function, +@code{gplot}, is + +@example +gplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} +@end example + +@noindent +where the @var{ranges}, @var{using}, @var{title}, and @var{style} +arguments are optional, and the @var{using}, @var{title} and @var{style} +qualifiers may appear in any order after the expression. You may plot +multiple expressions with a single command by separating them with +commas. Each expression may have its own set of qualifiers. + +The optional item @var{ranges} has the syntax + +@example +[ x_lo : x_up ] [ y_lo : y_up ] +@end example + +@noindent +and may be used to specify the ranges for the axes of the plot, +independent of the actual range of the data. The range for the y axes +and any of the individual limits may be omitted. A range @code{[:]} +indicates that the default limits should be used. This normally means +that a range just large enough to include all the data points will be +used. + +The expression to be plotted must not contain any literal matrices +(e.g. @code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to +distinguish a plot range from a matrix of data. + +See the help for @code{gnuplot} for a description of the syntax for the +optional items. + +By default, the @code{gplot} command plots the second column of a matrix +versus the first. If the matrix only has one column, it is taken as a +vector of y-coordinates and the x-coordinate is taken as the element +index, starting with zero. For example, + +@example +gplot rand (100,1) with linespoints +@end example + +@noindent +will plot 100 random values and connect them with lines. When +@code{gplot} is used to plot a column vector, the indices of the +elements are taken as x values. + + If there are more than two columns, you can +choose which columns to plot with the @var{using} qualifier. For +example, given the data + +@example +x = (-10:0.1:10)'; +data = [x, sin(x), cos(x)]; +@end example + +@noindent +the command + +@example +gplot [-11:11] [-1.1:1.1] data with lines, data using 1:3 with impulses +@end example + +@noindent +will plot two lines. The first line is generated by the command +@code{data with lines}, and is a graph of the sine function over the +range -10 to 10. The data is taken from the first two columns of the +matrix because columns to plot were not specified with the @var{using} +qualifier. + +The clause @code{using 1:3} in the second part of this plot command +specifies that the first and third columns of the matrix @code{data} +should be taken as the values to plot. + +In this example, the ranges have been explicitly specified to be a bit +larger than the actual range of the data so that the curves do not touch +the border of the plot. + +@findex set +@findex show +@findex replot + +In addition to the basic plotting commands, the whole range of +@code{set} and @code{show} commands from @code{gnuplot} are available, +as is @code{replot}. + +The @code{set} and @code{show} commands allow you to set and show +@code{gnuplot} parameters. For more information about the set and show +commands, see the @code{gnuplot} user's guide (also available on line if +you run @code{gnuplot} directly, instead of running it from Octave). + +The @code{replot} command allows you to force the plot to be +redisplayed. This is useful if you have changed something about the +plot, such as the title or axis labels. The @code{replot} command also +accepts the same arguments as @code{gplot} or @code{gsplot} (except for +data ranges) so you can add additional lines to existing plots. + +For example, + +@example +set term tek40 +set output "/dev/plotter" +set title "sine with lines and cosine with impulses" +replot "sin (x) w l" +@end example + +will change the terminal type for plotting, add a title to the current +plot, add a graph of sin (x) to the plot, and force the new plot to be +sent to the plot device. This last step is normally required in order +to update the plot. This default is reasonable for slow terminals or +hardcopy output devices because even when you are adding additional +lines with a replot command, gnuplot always redraws the entire plot, and +you probably don't want to have a completely new plot generated every +time something as minor as an axis label changes. + +@vindex automatic_replot + +Since this may not matter as much on faster terminals, you can tell +Octave to redisplay the plot each time anything about it changes by +setting the value of the builtin variable @code{automatic_replot} to the +value @code{"true"}. + +Note that NaN values in the plot data are automatically omitted, and +Inf values are converted to a very large value before calling gnuplot. + +@c XXX FIXME XXX -- add info about what to do to get plots on remote X +@c terminals. People often forget how to properly set DISPLAY and run +@c xhost. + +@c XXX FIXME XXX -- add info about getting paper copies of plots. + +The @sc{Matlab}-style two-dimensional plotting commands are: + +@cindex plotting +@cindex graphics + +@ftable @code +@item plot (@var{args}) +This function produces two-dimensional plots. Many different +combinations of arguments are possible. The simplest form is + +@example +plot (y) +@end example + +@noindent +where the argument is taken as the set of @var{y} coordinates and the +@var{x} coordinates are taken to be the indices of the elements, +starting with 1. + +If more than one argument is given, they are interpreted as + +@example +plot (x [, y] [, fmt] ...) +@end example + +@noindent +where @var{y} and @var{fmt} are optional, and any number of argument +sets may appear. The @var{x} and @var{y} values are +interpreted as follows: + +@itemize @bullet +@item +If a single data argument is supplied, it is taken as the set of @var{y} +coordinates and the @var{x} coordinates are taken to be the indices of +the elements, starting with 1. + +@item +If the first argument is a vector and the second is a matrix, the +the vector is plotted versus the columns (or rows) of the matrix. +(using whichever combination matches, with columns tried first.) + +@item +If the first argument is a matrix and the second is a vector, the +the columns (or rows) of the matrix are plotted versus the vector. +(using whichever combination matches, with columns tried first.) + +@item +If both arguments are vectors, the elements of @var{y} are plotted versus +the elements of @var{x}. + +@item +If both arguments are matrices, the columns of @var{y} are plotted +versus the columns of @var{x}. In this case, both matrices must have +the same number of rows and columns and no attempt is made to transpose +the arguments to make the number of rows match. + +If both arguments are scalars, a single point is plotted. +@end itemize + +The @var{fmt} argument, if present is interpreted as follows. If +@var{fmt} is missing, the default gnuplot line style is assumed. + +@table @asis +@item @samp{-} +Set lines plot style (default). + +@item @samp{.} +Set dots plot style. + +@item @samp{@@} +Set points plot style. + +@item @samp{-@@} +Set linespoints plot style. + +@item @samp{^} +Set impulses plot style. + +@item @samp{L} +Set steps plot style. + +@item @samp{#} +Set boxes plot style. + +@item @samp{~} +Set errorbars plot style. + +@item @samp{#~} +Set boxerrorbars plot style. + +@item @samp{n} +Interpreted as the plot color if @var{n} is an integer in the range 1 to +6. + +@item @samp{nm} +If @var{nm} is a two digit integer and @var{m} is an integer in the +range 1 to 6, @var{m} is interpreted as the point style. This is only +valid in combination with the @code{@@} or @code{-@@} specifiers. + +@item @samp{c} +If @var{c} is one of @var{"r"}, @var{"g"}, @var{"b"}, @var{"m"}, +@var{"c"}, or @var{"w"}, it is interpreted as the plot color (red, +green, blue, magenta, cyan, or white). + +@item @samp{+} +@itemx @samp{*} +@itemx @samp{o} +@itemx @samp{x} +Used in combination with the points or linespoints styles, set the point +style. +@end table + +The color line styles have the following meanings on terminals that +support color. + +@example +Number Gnuplot colors (lines)points style + 1 red * + 2 green + + 3 blue o + 4 magenta x + 5 cyan house + 6 brown there exists +@end example + +Here are some plot examples: + +@example +plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+") +@end example + +This command will plot @var{y} with points of type 2 (displayed as +@code{+}) and color 1 (red), @var{y2} with lines, @var{y3} with lines of +color 4 (magenta) and @var{y4} with points displayed as @code{+}. + +@example +plot (b, "*") +@end example + +This command will plot the data in @var{b} will be plotted with points +displayed as @code{*}. + +@item hold +Tell Octave to `hold' the current data on the plot when executing +subsequent plotting commands. This allows you to execute a series of +plot commands and have all the lines end up on the same figure. The +default is for each new plot command to clear the plot device first. +For example, the command + +@example +hold on +@end example + +@noindent +turns the hold state on. An argument of @code{off} turns the hold state +off, and @code{hold} with no arguments toggles the current hold state. + +@item ishold +Returns 1 if the next line will be added to the current plot, or 0 if +the plot device will be cleared before drawing the next line. + +@item loglog (@var{args}) +Make a two-dimensional plot using log scales for both axes. See the +description of @code{plot} above for a description of the arguments that +@code{loglog} will accept. + +@item semilogx (@var{args}) +Make a two-dimensional plot using a log scale for the @var{x} axis. See +the description of @code{plot} above for a description of the arguments +that @code{semilogx} will accept. + +@item semilogy (@var{args}) +Make a two-dimensional plot using a log scale for the @var{y} axis. See +the description of @code{plot} above for a description of the arguments +that @code{semilogy} will accept. + +@item contour (@var{z}, @var{n}, @var{x}, @var{y}) +Make a contour plot of the three-dimensional surface described by +@var{z}. Someone needs to improve @code{gnuplot}'s contour routines +before this will be very useful. + +@item polar (@var{theta}, @var{rho}) +Make a two-dimensional plot given polar the coordinates @var{theta} and +@var{rho}. +@end ftable + +@node Three-Dimensional Plotting, Miscellaneous Plotting Functions, Two-Dimensional Plotting, Plotting +@section Three-Dimensional Plotting + +The syntax for Octave's three-dimensional plotting function, +@code{gsplot}, is + +@example +gsplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} +@end example + +@noindent +where the @var{ranges}, @var{using}, @var{title}, and @var{style} +arguments are optional, and the @var{using}, @var{title} and @var{style} +qualifiers may appear in any order after the expression. You may plot +multiple expressions with a single command by separating them with +commas. Each expression may have its own set of qualifiers. + +The optional item @var{ranges} has the syntax + +@example +[ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ] +@end example + +@noindent +and may be used to specify the ranges for the axes of the plot, +independent of the actual range of the data. The range for the y and z +axes and any of the individual limits may be omitted. A range +@code{[:]} indicates that the default limits should be used. This +normally means that a range just large enough to include all the data +points will be used. + +The expression to be plotted must not contain any literal matrices (e.g. +@code{[ 1, 2; 3, 4 ]}) since it is nearly impossible to distinguish a +plot range from a matrix of data. + +See the help for @code{gnuplot} for a description of the syntax for the +optional items. + +By default, the @code{gsplot} command plots each column of the +expression as the z value, using the row index as the x value, and the +column index as the y value. The indices are counted from zero, not +one. For example, + +@example +gsplot rand (5, 2) +@end example + +@noindent +will plot a random surface, with the x and y values taken from the row +and column indices of the matrix. + +If parametric plotting mode is set (using the command +@samp{set parametric}, then @code{gsplot} takes the columns of the +matrix three at a time as the x, y and z values that define a line in +three space. Any extra columns are ignored, and the x and y values are +expected to be sorted. For example, with @samp{parametric} set, it +makes sense to plot a matrix like +@iftex +@tex +$$ +\left[\matrix{ +1 & 1 & 3 & 2 & 1 & 6 & 3 & 1 & 9 \cr +1 & 2 & 2 & 2 & 2 & 5 & 3 & 2 & 8 \cr +1 & 3 & 1 & 2 & 3 & 4 & 3 & 3 & 7}\right] +$$ +@end tex +@end iftex +@ifinfo + +@example +1 1 3 2 1 6 3 1 9 +1 2 2 2 2 5 3 2 8 +1 3 1 2 3 4 3 3 7 +@end example +@end ifinfo + +@noindent +but not @code{rand (5, 30)}. + +The @sc{Matlab}-style three-dimensional plotting commands are: + +@ftable @code +@item mesh (@var{x}, @var{y}, @var{z}) +Plot a mesh given matrices @code{x}, and @var{y} from @code{meshdom} and +a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of +the mesh. + +@item meshdom (@var{x}, @var{y}) +Given vectors of @var{x} and @var{y} coordinates, return two matrices +corresponding to the @var{x} and @var{y} coordinates of the mesh. + +See the file @file{sombrero.m} for an example of using @code{mesh} and +@code{meshdom}. +@end ftable + +@node Miscellaneous Plotting Functions, , Three-Dimensional Plotting, Plotting +@section Miscellaneous Plotting Functions + +@ftable @code +@item bar (@var{x}, @var{y}) +Given two vectors of x-y data, @code{bar} produces a bar graph. + +If only one argument is given, it is taken as a vector of y-values +and the x coordinates are taken to be the indices of the elements. + +If two output arguments are specified, the data are generated but +not plotted. For example, + +@example +bar (x, y); +@end example + +@noindent +and + +@example +[xb, yb] = bar (x, y); +plot (xb, yb); +@end example + +@noindent +are equivalent. + +@item grid +For two-dimensional plotting, force the display of a grid on the plot. + +@item stairs (@var{x}, @var{y}) +Given two vectors of x-y data, bar produces a `stairstep' plot. + +If only one argument is given, it is taken as a vector of y-values +and the x coordinates are taken to be the indices of the elements. + +If two output arguments are specified, the data are generated but +not plotted. For example, + +@example +stairs (x, y); +@end example + +@noindent +and + +@example +[xs, ys] = stairs (x, y); +plot (xs, ys); +@end example + +@noindent +are equivalent. + +@item title (@var{string}) +Specify a title for the plot. If you already have a plot displayed, use +the command @code{replot} to redisplay it with the new title. + +@item xlabel (@var{string}) +@itemx ylabel (@var{string}) +Specify x and y axis labels for the plot. If you already have a plot +displayed, use the command @code{replot} to redisplay it with the new +labels. + +@item sombrero (@var{n}) +Display a classic three-dimensional mesh plot. The parameter @var{n} +allows you to increase the resolution. + +@item clearplot +@itemx clg +Clear the plot window and any titles or axis labels. The name +@code{clg} is aliased to @code{clearplot} for compatibility with @sc{Matlab}. + +The commands @samp{gplot clear}, @samp{gsplot clear}, and @samp{replot +clear} are equivalent to @samp{clearplot}. (Previously, commands like +@samp{gplot clear} would evaluate @samp{clear} as an ordinary expression +and clear all the visible variables.) + +@item closeplot +Close stream to the @code{gnuplot} subprocess. If you are using X11, +this will close the plot window. + +@item purge_tmp_files +Delete the temporary files created by the plotting commands. + +Octave creates temporary data files for @code{gnuplot} and then sends +commands to @code{gnuplot} through a pipe. Octave will delete the +temporary files on exit, but if you are doing a lot of plotting you may +want to clean up in the middle of a session. + +A future version of Octave will eliminate the need to use temporary +files to hold the plot data. + +@item axis (@var{limits}) +Sets the axis limits for plots. + +The argument @var{limits} should be a 2, 4, or 6 element vector. The +first and second elements specify the lower and upper limits for the x +axis. The third and fourth specify the limits for the y axis, and the +fifth and sixth specify the limits for the z axis. + +With no arguments, @code{axis} turns autoscaling on. + +If your plot is already drawn, then you need to use @code{replot} before +the new axis limits will take effect. You can get this to happen +automatically by setting the built-in variable @code{automatic_replot} +to @code{"true"}. @xref{User Preferences}. + +@item hist (@var{y}, @var{x}) +Produce histogram counts or plots. + +With one vector input argument, plot a histogram of the values with +10 bins. The range of the histogram bins is determined by the range +of the data. + +Given a second scalar argument, use that as the number of bins. + +Given a second vector argument, use that as the centers of the bins, +with the width of the bins determined from the adjacent values in +the vector. + +Extreme values are lumped in the first and last bins. + +With two output arguments, produce the values @var{nn} and @var{xx} such +that @code{bar (@var{xx}, @var{nn})} will plot the histogram. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/poly.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,225 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Polynomial Manipulations, Nonlinear Equations, Linear Algebra, Top +@chapter Polynomial Manipulations + +In Octave, a polynomial is represented by its coefficients (arranged +in descending order). For example, a vector @var{c} of length @var{n+1} +corresponds to the following @var{n}-th order polynomial +@iftex +@tex +$$ + p (x) = c_1 x^n + ... + c_n x + c_{n+1}. +$$ +@end tex +@end iftex +@ifinfo + +@example +p(x) = c(1) x^n + ... + c(n) x + c(n+1). +@end example +@end ifinfo + +@ftable @code +@item compan (@var{c}) +Compute the companion matrix corresponding to polynomial coefficient +vector @var{c}. + +The companion matrix is +@iftex +@tex +$$ +A = \left[\matrix{ + -c_2/c_1 & -c_3/c_1 & \cdots & -c_n/c_1 & -c_{n+1}/c_1\cr + 1 & 0 & \cdots & 0 & 0 \cr + 0 & 1 & \cdots & 0 & 0 \cr + \vdots & & \ddots & \vdots & \vdots \cr + 0 & 0 & \cdots & 1 & 0}\right]. +$$ +@end tex +@end iftex +@ifinfo + +@smallexample + _ _ + | -c(2)/c(1) -c(3)/c(1) ... -c(n)/c(1) -c(n+1)/c(1) | + | 1 0 ... 0 0 | + | 0 1 ... 0 0 | +A = | . . . . . | + | . . . . . | + | . . . . . | + |_ 0 0 ... 1 0 _| +@end smallexample +@end ifinfo + +The eigenvalues of the companion matrix are equal to the roots of the +polynomial. + +@item conv (@var{a}, @var{b}) +Convolve two vectors. + +@code{y = conv (a, b)} returns a vector of length equal to +@code{length (a) + length (b) - 1}. +If @var{a} and @var{b} are polynomial coefficient vectors, @code{conv} +returns the coefficients of the product polynomial. + +@item deconv (@var{y}, @var{a}) +Deconvolve two vectors. + +@code{[b, r] = deconv (y, a)} solves for @var{b} and @var{r} such that +@code{y = conv (a, b) + r}. + +If @var{y} and @var{a} are polynomial coefficient vectors, @var{b} will +contain the coefficients of the polynomial quotient and @var{r} will be +a remander polynomial of lowest order. + +@item poly (@var{a}) +If @var{a} is a square @var{n}-by-@var{n} matrix, @code{poly (@var{a})} +is the row vector of the coefficients of @code{det (z * eye (n) - a)}, +the characteristic polynomial of @var{a}. If @var{x} is a vector, +@code{poly (@var{x})} is a vector of coefficients of the polynomial +whose roots are the elements of @var{x}. + +@item polyderiv (@var{c}) +Returns the coefficients of the derivative of the polynomial whose +coefficients are given by vector @var{c}. + +@item polyinteg (@var{c}) +Returns the coefficients of the integral the polynomial whose coefficients +are represented by the vector @var{c}. + +The constant of integration is set to zero. + +@item polyreduce (@var{c}) +Reduces a polynomial coefficient vector to a minimum number of terms by +stripping off any leading zeros. + +@item polyval (@var{c}, @var{x}) +Evaluate a polynomial. + +@code{polyval (@var{c}, @var{x})} will evaluate the polynomial at the +specified value of @var{x}. + +If @var{x} is a vector or matrix, the polynomial is evaluated at each of +the elements of @var{x}. + +@item polyvalm (@var{c}, @var{x}) +Evaluate a polynomial in the matrix sense. + +@code{polyvalm (@var{c}, @var{x})} will evaluate the polynomial in the +matrix sense, i.e. matrix multiplication is used instead of element by +element multiplication as is used in polyval. + +The argument @var{x} must be a square matrix. + +@item residue (@var{b}, @var{a}, @var{tol}) +If @var{b} and @var{a} are vectors of polynomial coefficients, then +residue calculates the partial fraction expansion corresponding to the +ratio of the two polynomials. + +The function @code{residue} returns @var{r}, @var{p}, @var{k}, and +@var{e}, where the vector @var{r} contains the residue terms, @var{p} +contains the pole values, @var{k} contains the coefficients of a direct +polynomial term (if it exists) and @var{e} is a vector containing the +powers of the denominators in the partial fraction terms. + +Assuming @var{b} and @var{a} represent polynomials +@iftex +@tex +$P(s)$ and $Q(s)$ +@end tex +@end iftex +@ifinfo + P (s) and Q(s) +@end ifinfo + we have: +@iftex +@tex +$$ +{P(s)\over Q(s)} = \sum_{m=1}^M {r_m\over (s-p_m)^e_m} + + \sum_{n=1}^N k_n s^{N-n}. +$$ +@end tex +@end iftex +@ifinfo + +@example + P(s) M r(m) N + ---- = SUM ------------- + SUM k(n)*s^(N-n) + Q(s) m=1 (s-p(m))^e(m) n=1 +@end example +@end ifinfo + +@noindent +where @var{M} is the number of poles (the length of the @var{r}, +@var{p}, and @var{e} vectors) and @var{N} is the length of the @var{k} +vector. + +The argument @var{tol} is optional, and if not specified, a default +value of 0.001 is assumed. The tolerance value is used to determine +whether poles with small imaginary components are declared real. It is +also used to determine if two poles are distinct. If the ratio of the +imaginary part of a pole to the real part is less than @var{tol}, the +imaginary part is discarded. If two poles are farther apart than +@var{tol} they are distinct. For example, + +Example: + +@example + b = [1, 1, 1]; + a = [1, -5, 8, -4]; + + [r, p, k, e] = residue (b, a) +@end example + +@noindent +returns + +@example +r = [-2, 7, 3] + +p = [2, 2, 1] + +k = [](0x0) + +e = [1, 2, 1] +@end example + +@noindent +which implies the following partial fraction expansion +@iftex +@tex +$$ +{s^2+s+1\over s^3-5s^2+8s-4} = {-2\over s-2} + {7\over (s-2)^2} + {3\over s-1} +$$ +@end tex +@end iftex +@ifinfo + +@example + s^2 + s + 1 -2 7 3 + ------------------- = ----- + ------- + ----- + s^3 - 5s^2 + 8s - 4 (s-2) (s-2)^2 (s-1) +@end example +@end ifinfo + +@item roots (@var{v}) + +For a vector @var{v} with @var{n} components, return +the roots of the polynomial +@iftex +@tex +$$ +v_1 z^{n-1} + \cdots + v_{n-1} z + v_n. +$$ +@end tex +@end iftex +@ifinfo + +@example +v(1) * z^(n-1) + ... + v(n-1) * z + v(n). +@end example +@end ifinfo +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/preface.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,188 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Preface, Copying, Top, Top +@unnumbered Preface +@cindex acknowledgements +@cindex contributors +@cindex history + +Octave was originally intended to be companion software for an +undergraduate-level textbook on chemical reactor design being written by +James B. Rawlings of the University of Wisconsin-Madison and John +G. Ekerdt of the University of Texas. + +Clearly, Octave is now much more than just another `courseware' package +with limited utility beyond the classroom. Although our initial goals +were somewhat vague, we knew that we wanted to create something that +would enable students to solve realistic problems, and that they could +use for many things other than chemical reactor design problems. + +There are those who would say that we should be teaching the students +Fortran instead, because that is the computer language of engineering, +but every time we have tried that, the students have spent far too much +time trying to figure out why their Fortran code crashes and not enough +time learning about chemical engineering. With Octave, most students +pick up the basics quickly, and are using it confidently in just a few +hours. + +Although it was originally intended to be used to teach reactor design, +it has been used in several other undergraduate and graduate +courses in the Chemical Engineering Department at the University of +Texas, and the math department at the University of Texas has been using +it for teaching differential equations and linear algebra as well. If +you find it useful, please let us know. We are always interested to +find out how Octave is being used in other places. + +Virtually everyone thinks that the name Octave has something to do with +music, but it is actually the name of a former professor of mine who +wrote a famous textbook on chemical reaction engineering, and who was +also well known for his ability to do quick `back of the envelope' +calculations. We hope that this software will make it possible for many +people to do more ambitious computations just as easily. + +Everyone is encouraged to share this software with others under the +terms of the GNU General Public License (@pxref{Copying}) as described +at the beginning of this manual. You are also encouraged to help make +Octave more useful by writing and contributing additional functions for +it, and by reporting any problems you may have. + +Many people have already contributed to Octave's development. In +addition to John W. Eaton, the following people have helped write parts +of Octave or helped out in various other ways. + +@c Once lp_solve has been added, don't forget to include the lp_solve +@c author, and Kantor, for providing an example. + +@itemize @bullet +@item +Thomas Baier (baier@@ci.tuwien.ac.at) wrote the original versions of +@code{popen}, @code{pclose}, @code{execute}, @code{sync_system}, and +@code{async_system}. + +@item +Karl Berry (karl@@cs.umb.edu) wrote the @code{kpathsea} library that +allows Octave to recursively search directory paths for function and +script files. + +@item +Georg Beyerle (gbeyerle@@awi-potsdam.de) contributed code to save values +in @sc{Matlab}'s @file{.mat}-file format, and has provided many useful bug +reports and suggestions. + +@item +John Campbell (jcc@@bevo.che.wisc.edu) wrote most of the file and +C-style input and output functions. + +@item +Brian Fox (bfox@@gnu.ai.mit.edu) wrote the @code{readline} library used +for command history editing, and the portion of this manual that +documents it. + +@item +A. Scottedward Hodel (scotte@@eng.auburn.edu) contributed a number +of functions including @code{expm}, @code{qzval}, @code{qzhess}, +@code{syl}, @code{lyap}, and @code{balance}. + +@item +Kurt Hornik (Kurt.Hornik@@ci.tuwien.ac.at) provided the @code{corrcoef}, +@code{cov}, @code{fftconv}, @code{fftfilt}, @code{gcd}, @code{lcd}, +@code{kurtosis}, @code{null}, @code{orth}, @code{poly}, @code{polyfit}, +@code{roots}, and @code{skewness} functions, supplied documentation for +these and numerous other functions, rewrote the Emacs mode for editing +Octave code and provided its documentation, and has helped tremendously +with testing. He has also been a constant source of new ideas for +improving Octave. + +@item +Phil Johnson (johnsonp@@nicco.sscnet.ucla.edu) has helped to make Linux +releases available. + +@item +Friedrich Leisch (leisch@@ci.tuwien.ac.at) provided the +@code{mahalanobis} function. + +@item +Ken Neighbors (wkn@@leland.stanford.edu) has provided many useful bug +reports and comments on @sc{Matlab} compatibility. + +@item +Rick Niles (niles@@axp745.gsfc.nasa.gov) rewrote Octave's plotting +functions to add line styles and the ability to specify an unlimited +number of lines in a single call. He also continues to track down +odd incompatibilities and bugs. + +@item +Mark Odegard (meo@@sugarland.unocal.com) provided the initial +implementation of @code{fread}, @code{fwrite}, @code{feof}, and +@code{ferror}. + +@item +Tony Richardson (tony@@guts.biomed.uakron.edu) wrote Octave's image +processing functions as well as most of the original polynomial +functions. + +@item +R. Bruce Tenison (Bruce.Tenison@@eng.auburn.edu) wrote the @code{hess} and +@code{schur} functions. + +@item +Teresa Twaroch (twaroch@@ci.tuwien.ac.at) provided the functions +@code{gls} and @code{ols}. + +@item +Andreas Weingessel (Andreas.Weingessel@@ci.tuwien.ac.at) wrote the +audio functions @code{lin2mu}, @code{loadaudio}, @code{mu2lin}, +@code{playaudio}, @code{record}, @code{saveaudio}, and @code{setaudio}. + +@item +Fook Fah Yap (ffy@@eng.cam.ac.uk) provided the @code{fft} and +@code{ifft} functions and valuable bug reports for early versions. +@end itemize + +Special thanks to the following people and organizations for +supporting the development of Octave: + +@itemize @bullet +@item +Digital Equipment Corporation, for an equipment grant as part of their +External Research Program. + +@item +Sun Microsystems, Inc., for an Academic Equipment grant. + +@item +International Business Machines, Inc., for providing equipment as part +of a grant to the University of Texas College of Engineering. + +@item +Texaco Chemical Company, for providing funding to continue the +development of this software. + +@item +The University of Texas College of Engineering, for providing a +Challenge for Excellence Research Supplement, and for providing an +Academic Development Funds grant. + +@item +The State of Texas, for providing funding through the Texas +Advanced Technology Program under Grant No. 003658-078. + +@item +Noel Bell, Senior Engineer, Texaco Chemical Company, Austin Texas. + +@item +James B. Rawlings, Professor, University of Wisconsin-Madison, +Department of Chemical Engineering. + +@item +Richard Stallman, for writing GNU. +@end itemize + +Portions of this document have been adapted from the @code{gawk}, +@code{readline}, @code{gcc}, and C library manuals, published by the Free +Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +This project would not have been possible without the GNU software used +in and used to produce Octave.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/program.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,390 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Programming Utilities, Amusements, Help, Top +@chapter Programming Utilities + +@menu +* Evaluating Strings as Commands:: +* Miscellaneous Utilities:: +@end menu + +@node Evaluating Strings as Commands, Miscellaneous Utilities, Programming Utilities, Programming Utilities +@section Evaluating Strings as Commands + +@findex eval + +It is often useful to evaluate a string as if it were an Octave program, +or use a string as the name of a function to call. These functions are +necessary in order to evaluate commands that are not known until run +time, or to write functions that will need to call user-supplied +functions. + +The function @code{eval (@var{command})} parses @var{command} and +evaluates it as if it were an Octave program, returning the last value +computed. The @var{command} is evaluated in the current context, so any +results remain available after @code{eval} returns. For example, + +@example +octave:13> a +error: `a' undefined +octave:14> eval ("a = 13") +a = 13 +ans = 13 +octave:15> a +a = 13 +@end example + +In this case, two values are printed: one for the expression that was +evaluated, and one for the value returned from @code{eval}. Just as +with any other expression, you can turn printing off by ending the +expression in a semicolon. For example, + +@example +octave:13> a +error: `a' undefined +octave:14> eval ("a = 13;") +ans = 13 +octave:15> a +a = 13 +@end example + +@findex feval + +The function @code{feval (@var{name}, ...)} can be used to evaluate +the function named @var{name}. Any arguments after the first are passed +on to the named function. For example, + +@example +octave:12> feval ("acos", -1) +ans = 3.1416 +@end example + +@noindent +calls the function @code{acos} with the argument @samp{-1}. + +The function @code{feval} is necessary in order to be able to write +functions that call user-supplied functions, because Octave does not +have a way to declare a pointer to a function (like C) or to declare a +special kind of variable that can be used to hold the name of a function +(like @code{EXTERNAL} in Fortran). Instead, you must refer to functions +by name, and use @code{feval} to call them. + +For example, here is a +simple-minded function for finding the root of a function of one +variable: + +@cindex Fordyce, A. P. +@findex newtroot + +@example +@group +function result = newtroot (fname, x) + +# usage: newtroot (fname, x) +# +# fname : a string naming a function f(x). +# x : initial guess + + delta = tol = sqrt (eps); + maxit = 200; + fx = feval (fname, x); + for i = 1:maxit + if (abs (fx) < tol) + result = x; + return; + else + fx_new = feval (fname, x + delta); + deriv = (fx_new - fx) / delta; + x = x - fx / deriv; + fx = fx_new; + endif + endfor + + result = x; + +endfunction +@end group +@end example + +Note that this is only meant to be an example of calling user-supplied +functions and should not be taken too seriously. In addition to using a +more robust algorithm, any serious code would check the number and type +of all the arguments, ensure that the supplied function really was a +function, etc. + +@node Miscellaneous Utilities, , Evaluating Strings as Commands, Programming Utilities +@section Miscellaneous Utilities + +The following functions allow you to determine the size of a variable or +expression, find out whether a variable exists, print error messages, or +delete variable names from the symbol table. + +@ftable @code +@item columns (@var{a}) +Return the number of columns of @var{a}. + +@item rows (@var{a}) +Return the number of rows of @var{a}. + +@item length (@var{a}) +Return the number of rows of @var{a} or the number of columns of +@var{a}, whichever is larger. + +@item size (@var{a} [, @var{n}]) +Return the number rows and columns of @var{a}. + +With one input argument and one output argument, the result is returned +in a 2 element row vector. If there are two output arguments, the +number of rows is assigned to the first, and the number of columns to +the second. For example, + +@example +@group +octave:13> size ([1, 2; 3, 4; 5, 6]) +ans = + + 3 2 + +octave:14> [nr, nc] = size ([1, 2; 3, 4; 5, 6]) +nr = 3 + +nc = 2 +@end group +@end example + +If given a second argument of either 1 or 2, @code{size} will return +only the row or column dimension. For example + +@example +octave:15> size ([1, 2; 3, 4; 5, 6], 2) +ans = 2 +@end example + +@noindent +returns the number of columns in the given matrix. + +@item is_global (@var{a}) +Return 1 if @var{a} is globally visible. Otherwise, return 0. + +@item is_matrix (@var{a}) +Return 1 if @var{a} is a matrix. Otherwise, return 0. + +@item is_vector (@var{a}) +Return 1 if @var{a} is a vector. Otherwise, return 0. + +@item is_scalar (@var{a}) +Return 1 if @var{a} is a scalar. Otherwise, return 0. + +@item is_square (@var{x}) +If @var{x} is a square matrix, then return the dimension of @var{x}. +Otherwise, return 0. + +@item is_symmetric (@var{x}, @var{tol}) +If @var{x} is symmetric within the tolerance specified by @var{tol}, +then return the dimension of @var{x}. Otherwise, return 0. If +@var{tol} is omitted, use a tolerance equal to the machine precision. + +@item isstr (@var{a}) +Return 1 if @var{a} is a string. Otherwise, return 0. + +@item isempty (@var{a}) +Return 1 if @var{a} is an empty matrix (either the number of rows, or +the number of columns, or both are zero). Otherwise, return 0. + +@item clear @var{pattern} ... +Delete the names matching the given patterns from the symbol table. The +pattern may contain the following special characters: +@table @code +@item ? +Match any single character. + +@item * +Match zero or more characters. + +@item [ @var{list} ] +Match the list of characters specified by @var{list}. If the first +character is @code{!} or @code{^}, match all characters except those +specified by @var{list}. For example, the pattern @samp{[a-zA-Z]} will +match all lower and upper case alphabetic characters. +@end table + +For example, the command + +@example +clear foo b*r +@end example + +@noindent +clears the name @code{foo} and all names that begin with the letter +@code{b} and end with the letter @code{r}. + +If @code{clear} is called without any arguments, all user-defined +variables (local and global) are cleared from the symbol table. If +@code{clear} is called with at least one argument, only the visible +names matching the arguments are cleared. For example, suppose you have +defined a function @code{foo}, and then hidden it by performing the +assignment @code{foo = 2}. Executing the command @samp{clear foo} once +will clear the variable definition and restore the definition of +@code{foo} as a function. Executing @samp{clear foo} a second time will +clear the function definition. + +This command may not be used within a function body. + +@item who @var{options} @var{pattern} ... +List currently defined symbols matching the given patterns. The +following are valid options. They may be shortened to one character but +may not be combined. + +@table @code +@item -all +List all currently defined symbols. + +@item -builtins +List built-in variables and functions. This includes all currently +compiled function files, but does not include all function files that +are in the @code{LOADPATH}. + +@item -functions +List user-defined functions. + +@item -long +Print a long listing including the type and dimensions of any symbols. +The symbols in the first column of output indicate whether it is +possible to redefine the symbol, and whether it is possible for it to be +cleared. + +@item -variables +List user-defined variables. +@end table + +Valid patterns are the same as described for the @code{clear} command +above. If no patterns are supplied, all symbols from the given category +are listed. By default, only user defined functions and variables +visible in the local scope are displayed. + +@findex whos + +The command @code{whos} is equivalent to @code{who -long}. + +@item exist (@var{name}) +Return 1 if the name exists as a variable, and 2 if the name (after +appending @samp{.m}) is a function file in the path. Otherwise, return +0. + +@item error (@var{msg}) +Print the message @var{msg}, prefixed by the string @samp{error: }, and +set Octave's internal error state such that control will return to the +top level without evaluating any more commands. This is useful for +aborting from functions. + +If @var{msg} does not end with a new line character, Octave will print a +traceback of all the function calls leading to the error. For example, + +@example +function f () g () end +function g () h () end +function h () nargin == 1 || error ("nargin != 1"); end +f () +error: nargin != 1 +error: evaluating index expression near line 1, column 30 +error: evaluating binary operator `||' near line 1, column 27 +error: called from `h' +error: called from `g' +error: called from `f' +@end example + +@noindent +produces a list of messages that can help you to quickly locate the +exact location of the error. + +If @var{msg} ends in a new line character, Octave will only print +@var{msg} and will not display any traceback messages as it returns +control to the top level. For example, modifying the error message +in the previous example to end in a new line causes Octave to only print +a single message: + +@example +function h () nargin == 1 || error ("nargin != 1\n"); end +f () +error: nargin != 1 +@end example + +@item warning (@var{msg}) +Print the message @var{msg} prefixed by the string @samp{warning: }. + +@item usage (@var{msg}) +Print the message @var{msg}, prefixed by the string @samp{usage: }, and +set Octave's internal error state such that control will return to the +top level without evaluating any more commands. This is useful for +aborting from functions. + +After @code{usage} is evaluated, Octave will print a traceback of all +the function calls leading to the usage message. + +@item perror (@var{name}, @var{num}) +Print the error message for function @var{name} corresponding to the +error number @var{num}. This function is intended to be used to print +useful error messages for those functions that return numeric error +codes. + +@item menu (@var{title}, @var{opt1}, @dots{}) +Print a title string followed by a series of options. Each option will +be printed along with a number. The return value is the number of the +option selected by the user. This function is useful for interactive +programs. There is no limit to the number of options that may be passed +in, but it may be confusing to present more than will fit easily on one +screen. + +@item document @var{symbol} @var{text} +Set the documentation string for @var{symbol} to @var{text}. + +@item file_in_path (@var{path}, @var{file}) +Return the absolute name name of @var{file} if it can be found in +@var{path}. The value of @var{path} should be a colon-separated list of +directories in the format described for the built-in variable +@code{LOADPATH}. + +If the file cannot be found in the path, an empty matrix is returned. +For example, + +@example +octave:13> file_in_path (LOADPATH, "nargchk.m") +ans = /usr/local/lib/octave/1.1.0/m/general/nargchk.m +@end example + +@item nargchk (@var{nargin_min}, @var{nargin_max}, @var{n}) +If @var{n} is in the range @var{nargin_min} through @var{nargin_max} +inclusive, return the empty matrix. Otherwise, return a message +indicating whether @var{n} is too large or too small. + +This is useful for checking to see that the number of arguments supplied +to a function is within an acceptable range. + +@item octave_tmp_file_name +Return a unique temporary file name. + +Since the named file is not opened, by @code{octave_tmp_file_name}, it +is possible (though relatively unlikely) that it will not be available +by the time your program attempts to open it. + +@item type @var{name} ... +@item type [-q] @var{name} ... +Display the definition of each @var{name} that refers to a function. + +Normally also displays if each @var{name} is user-defined or builtin; +the @code{-q} option suppresses this behaviour. + +Currently, Octave can only display functions that can be compiled +cleanly, because it uses its internal representation of the function to +recreate the program text. + +Comments are not displayed because Octave's parser currently discards +them as it converts the text of a function file to its internal +representation. This problem may be fixed in a future release. + +@item which @var{name} ... +Display the type of each @var{name}. If @var{name} is defined from a +function file, the full name of the file is also displayed. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/psfig.tex Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,778 @@ +% Psfig/TeX Release 1.6b +% dvips version +% +% All psfig/tex software, documentation, and related files +% in this distribution of psfig/tex are +% Copyright 1987, 1988, 1991 Trevor J. Darrell +% +% Permission is granted for use and non-profit distribution of psfig/tex +% providing that this notice be clearly maintained. The right to +% distribute any portion of psfig/tex for profit or as part of any commercial +% product is specifically reserved for the author(s) of that portion. +% +% Thanks to Greg Hager (GDH) and Ned Batchelder for their contributions +% to this project. +% +% Modified by J. Daniel Smith on 9 October 1990 to accept the +% %%BoundingBox: comment with or without a space after the colon. Stole +% file reading code from Tom Rokicki's EPSF.TEX file (see below). +% +% More modifications by J. Daniel Smith on 29 March 1991 to allow the +% the included PostScript figure to be rotated. The amount of +% rotation is specified by the "angle=" parameter of the \psfig command. +% +% Modified by Robert Russell on June 25, 1991 to allow users to specify +% .ps filenames which don't yet exist, provided they explicitly provide +% boundingbox information via the \psfig command. Note: This will only work +% if the "file=" parameter follows all four "bb???=" parameters in the +% command. This is due to the order in which psfig interprets these params. +% +% 3 Jul 1991 JDS check if file already read in once +% 4 Sep 1991 JDS fixed incorrect computation of rotated +% bounding box +% + +% check to see if macros already loaded in (maybe some other file says +% "\input psfig") ... +\ifx\undefined\psfig\else\endinput\fi + +% +% from a suggestion by eijkhout@csrd.uiuc.edu to allow +% loading as a style file: +\edef\psfigRestoreAt{\catcode`@=\number\catcode`@\relax} +\catcode`\@=11\relax +\newwrite\@unused +\def\typeout#1{{\let\protect\string\immediate\write\@unused{#1}}} +\typeout{psfig/tex 1.6b} + + +%% Here's how you define your figure path. Should be set up with null +%% default and a user useable definition. +%\def\figurepath{./} +% The above definition for \figurepath is stupid. It restricts .ps +% files to existing only in the current directory or below. We +% redefine it properly. +\def\figurepath{} +\def\psfigurepath#1{\edef\figurepath{#1}} + +% +% @psdo control structure -- similar to Latex @for. +% I redefined these with different names so that psfig can +% be used with TeX as well as LaTeX, and so that it will not +% be vunerable to future changes in LaTeX's internal +% control structure, +% +\def\@nnil{\@nil} +\def\@empty{} +\def\@psdonoop#1\@@#2#3{} +\def\@psdo#1:=#2\do#3{\edef\@psdotmp{#2}\ifx\@psdotmp\@empty \else + \expandafter\@psdoloop#2,\@nil,\@nil\@@#1{#3}\fi} +\def\@psdoloop#1,#2,#3\@@#4#5{\def#4{#1}\ifx #4\@nnil \else + #5\def#4{#2}\ifx #4\@nnil \else#5\@ipsdoloop #3\@@#4{#5}\fi\fi} +\def\@ipsdoloop#1,#2\@@#3#4{\def#3{#1}\ifx #3\@nnil + \let\@nextwhile=\@psdonoop \else + #4\relax\let\@nextwhile=\@ipsdoloop\fi\@nextwhile#2\@@#3{#4}} +\def\@tpsdo#1:=#2\do#3{\xdef\@psdotmp{#2}\ifx\@psdotmp\@empty \else + \@tpsdoloop#2\@nil\@nil\@@#1{#3}\fi} +\def\@tpsdoloop#1#2\@@#3#4{\def#3{#1}\ifx #3\@nnil + \let\@nextwhile=\@psdonoop \else + #4\relax\let\@nextwhile=\@tpsdoloop\fi\@nextwhile#2\@@#3{#4}} +% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% file reading stuff from epsf.tex +% EPSF.TEX macro file: +% Written by Tomas Rokicki of Radical Eye Software, 29 Mar 1989. +% Revised by Don Knuth, 3 Jan 1990. +% Revised by Tomas Rokicki to accept bounding boxes with no +% space after the colon, 18 Jul 1990. +% Portions modified/removed for use in PSFIG package by +% J. Daniel Smith, 9 October 1990. +% +\newread\ps@stream +\newif\ifnot@eof % continue looking for the bounding box? +\newif\if@noisy % report what you're making? +\newif\if@atend % %%BoundingBox: has (at end) specification +\newif\if@psfile % does this look like a PostScript file? +% +% PostScript files should start with `%!' +% +{\catcode`\%=12\global\gdef\epsf@start{%!}} +\def\epsf@PS{PS} +% +\def\epsf@getbb#1{% +% +% The first thing we need to do is to open the +% PostScript file, if possible. +% +\openin\ps@stream=#1 +\ifeof\ps@stream\typeout{Error, File #1 not found}\else +% +% Okay, we got it. Now we'll scan lines until we find one that doesn't +% start with %. We're looking for the bounding box comment. +% + {\not@eoftrue \chardef\other=12 + \def\do##1{\catcode`##1=\other}\dospecials \catcode`\ =10 + \loop + \if@psfile + \read\ps@stream to \epsf@fileline + \else{ + \obeyspaces + \read\ps@stream to \epsf@tmp\global\let\epsf@fileline\epsf@tmp} + \fi + \ifeof\ps@stream\not@eoffalse\else +% +% Check the first line for `%!'. Issue a warning message if its not +% there, since the file might not be a PostScript file. +% + \if@psfile\else + \expandafter\epsf@test\epsf@fileline:. \\% + \fi +% +% We check to see if the first character is a % sign; +% if so, we look further and stop only if the line begins with +% `%%BoundingBox:' and the `(atend)' specification was not found. +% That is, the only way to stop is when the end of file is reached, +% or a `%%BoundingBox: llx lly urx ury' line is found. +% + \expandafter\epsf@aux\epsf@fileline:. \\% + \fi + \ifnot@eof\repeat + }\closein\ps@stream\fi}% +% +% This tests if the file we are reading looks like a PostScript file. +% +\long\def\epsf@test#1#2#3:#4\\{\def\epsf@testit{#1#2} + \ifx\epsf@testit\epsf@start\else +\typeout{Warning! File does not start with `\epsf@start'. It may not be a PostScript file.} + \fi + \@psfiletrue} % don't test after 1st line +% +% We still need to define the tricky \epsf@aux macro. This requires +% a couple of magic constants for comparison purposes. +% +{\catcode`\%=12\global\let\epsf@percent=%\global\def\epsf@bblit{%BoundingBox}} +% +% +% So we're ready to check for `%BoundingBox:' and to grab the +% values if they are found. We continue searching if `(at end)' +% was found after the `%BoundingBox:'. +% +\long\def\epsf@aux#1#2:#3\\{\ifx#1\epsf@percent + \def\epsf@testit{#2}\ifx\epsf@testit\epsf@bblit + \@atendfalse + \epsf@atend #3 . \\% + \if@atend + \if@verbose{ + \typeout{psfig: found `(atend)'; continuing search} + }\fi + \else + \epsf@grab #3 . . . \\% + \not@eoffalse + \global\no@bbfalse + \fi + \fi\fi}% +% +% Here we grab the values and stuff them in the appropriate definitions. +% +\def\epsf@grab #1 #2 #3 #4 #5\\{% + \global\def\epsf@llx{#1}\ifx\epsf@llx\empty + \epsf@grab #2 #3 #4 #5 .\\\else + \global\def\epsf@lly{#2}% + \global\def\epsf@urx{#3}\global\def\epsf@ury{#4}\fi}% +% +% Determine if the stuff following the %%BoundingBox is `(atend)' +% J. Daniel Smith. Copied from \epsf@grab above. +% +\def\epsf@atendlit{(atend)} +\def\epsf@atend #1 #2 #3\\{% + \def\epsf@tmp{#1}\ifx\epsf@tmp\empty + \epsf@atend #2 #3 .\\\else + \ifx\epsf@tmp\epsf@atendlit\@atendtrue\fi\fi} + + +% End of file reading stuff from epsf.tex +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% trigonometry stuff from "trig.tex" +\chardef\letter = 11 +\chardef\other = 12 + +\newif \ifdebug %%% turn me on to see TeX hard at work ... +\newif\ifc@mpute %%% don't need to compute some values +\c@mputetrue % but assume that we do + +\let\then = \relax +\def\r@dian{pt } +\let\r@dians = \r@dian +\let\dimensionless@nit = \r@dian +\let\dimensionless@nits = \dimensionless@nit +\def\internal@nit{sp } +\let\internal@nits = \internal@nit +\newif\ifstillc@nverging +\def \Mess@ge #1{\ifdebug \then \message {#1} \fi} + +{ %%% Things that need abnormal catcodes %%% + \catcode `\@ = \letter + \gdef \nodimen {\expandafter \n@dimen \the \dimen} + \gdef \term #1 #2 #3% + {\edef \t@ {\the #1}%%% freeze parameter 1 (count, by value) + \edef \t@@ {\expandafter \n@dimen \the #2\r@dian}% + %%% freeze parameter 2 (dimen, by value) + \t@rm {\t@} {\t@@} {#3}% + } + \gdef \t@rm #1 #2 #3% + {{% + \count 0 = 0 + \dimen 0 = 1 \dimensionless@nit + \dimen 2 = #2\relax + \Mess@ge {Calculating term #1 of \nodimen 2}% + \loop + \ifnum \count 0 < #1 + \then \advance \count 0 by 1 + \Mess@ge {Iteration \the \count 0 \space}% + \Multiply \dimen 0 by {\dimen 2}% + \Mess@ge {After multiplication, term = \nodimen 0}% + \Divide \dimen 0 by {\count 0}% + \Mess@ge {After division, term = \nodimen 0}% + \repeat + \Mess@ge {Final value for term #1 of + \nodimen 2 \space is \nodimen 0}% + \xdef \Term {#3 = \nodimen 0 \r@dians}% + \aftergroup \Term + }} + \catcode `\p = \other + \catcode `\t = \other + \gdef \n@dimen #1pt{#1} %%% throw away the ``pt'' +} + +\def \Divide #1by #2{\divide #1 by #2} %%% just a synonym + +\def \Multiply #1by #2%%% allows division of a dimen by a dimen + {{%%% should really freeze parameter 2 (dimen, passed by value) + \count 0 = #1\relax + \count 2 = #2\relax + \count 4 = 65536 + \Mess@ge {Before scaling, count 0 = \the \count 0 \space and + count 2 = \the \count 2}% + \ifnum \count 0 > 32767 %%% do our best to avoid overflow + \then \divide \count 0 by 4 + \divide \count 4 by 4 + \else \ifnum \count 0 < -32767 + \then \divide \count 0 by 4 + \divide \count 4 by 4 + \else + \fi + \fi + \ifnum \count 2 > 32767 %%% while retaining reasonable accuracy + \then \divide \count 2 by 4 + \divide \count 4 by 4 + \else \ifnum \count 2 < -32767 + \then \divide \count 2 by 4 + \divide \count 4 by 4 + \else + \fi + \fi + \multiply \count 0 by \count 2 + \divide \count 0 by \count 4 + \xdef \product {#1 = \the \count 0 \internal@nits}% + \aftergroup \product + }} + +\def\r@duce{\ifdim\dimen0 > 90\r@dian \then % sin(x+90) = sin(180-x) + \multiply\dimen0 by -1 + \advance\dimen0 by 180\r@dian + \r@duce + \else \ifdim\dimen0 < -90\r@dian \then % sin(-x) = sin(360+x) + \advance\dimen0 by 360\r@dian + \r@duce + \fi + \fi} + +\def\Sine#1% + {{% + \dimen 0 = #1 \r@dian + \r@duce + \ifdim\dimen0 = -90\r@dian \then + \dimen4 = -1\r@dian + \c@mputefalse + \fi + \ifdim\dimen0 = 90\r@dian \then + \dimen4 = 1\r@dian + \c@mputefalse + \fi + \ifdim\dimen0 = 0\r@dian \then + \dimen4 = 0\r@dian + \c@mputefalse + \fi +% + \ifc@mpute \then + % convert degrees to radians + \divide\dimen0 by 180 + \dimen0=3.141592654\dimen0 +% + \dimen 2 = 3.1415926535897963\r@dian %%% a well-known constant + \divide\dimen 2 by 2 %%% we only deal with -pi/2 : pi/2 + \Mess@ge {Sin: calculating Sin of \nodimen 0}% + \count 0 = 1 %%% see power-series expansion for sine + \dimen 2 = 1 \r@dian %%% ditto + \dimen 4 = 0 \r@dian %%% ditto + \loop + \ifnum \dimen 2 = 0 %%% then we've done + \then \stillc@nvergingfalse + \else \stillc@nvergingtrue + \fi + \ifstillc@nverging %%% then calculate next term + \then \term {\count 0} {\dimen 0} {\dimen 2}% + \advance \count 0 by 2 + \count 2 = \count 0 + \divide \count 2 by 2 + \ifodd \count 2 %%% signs alternate + \then \advance \dimen 4 by \dimen 2 + \else \advance \dimen 4 by -\dimen 2 + \fi + \repeat + \fi + \xdef \sine {\nodimen 4}% + }} + +% Now the Cosine can be calculated easily by calling \Sine +\def\Cosine#1{\ifx\sine\UnDefined\edef\Savesine{\relax}\else + \edef\Savesine{\sine}\fi + {\dimen0=#1\r@dian\advance\dimen0 by 90\r@dian + \Sine{\nodimen 0} + \xdef\cosine{\sine} + \xdef\sine{\Savesine}}} +% end of trig stuff +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\def\psdraft{ + \def\@psdraft{0} + %\typeout{draft level now is \@psdraft \space . } +} +\def\psfull{ + \def\@psdraft{100} + %\typeout{draft level now is \@psdraft \space . } +} + +\psfull + +\newif\if@draftbox +\def\psnodraftbox{ + \@draftboxfalse +} +\def\psdraftbox{ + \@draftboxtrue +} +\@draftboxtrue + +\newif\if@prologfile +\newif\if@postlogfile +\def\pssilent{ + \@noisyfalse +} +\def\psnoisy{ + \@noisytrue +} +\psnoisy +%%% These are for the option list. +%%% A specification of the form a = b maps to calling \@p@@sa{b} +\newif\if@bbllx +\newif\if@bblly +\newif\if@bburx +\newif\if@bbury +\newif\if@height +\newif\if@width +\newif\if@rheight +\newif\if@rwidth +\newif\if@angle +\newif\if@clip +\newif\if@verbose +\def\@p@@sclip#1{\@cliptrue} + +%%% GDH 7/26/87 -- changed so that it first looks in the local directory, +%%% then in a specified global directory for the ps file. +%%% RPR 6/25/91 -- changed so that it defaults to user-supplied name if +%%% boundingbox info is specified, assuming graphic will be created by +%%% print time. + +\def\@p@@sfile#1{\def\@p@sfile{null}% + \openin1=#1 + \ifeof1\closein1% + \openin1=\figurepath#1 + \ifeof1\typeout{Error, File #1 not found} + \if@bbllx\if@bblly\if@bburx\if@bbury% added 6/91 Rob Russell + \def\@p@sfile{#1}% + \fi\fi\fi\fi + \else\closein1 + \edef\@p@sfile{\figurepath#1}% + \fi% + \else\closein1% + \def\@p@sfile{#1}% + \fi} +\def\@p@@sfigure#1{\def\@p@sfile{null}% + \openin1=#1 + \ifeof1\closein1% + \openin1=\figurepath#1 + \ifeof1\typeout{Error, File #1 not found} + \if@bbllx\if@bblly\if@bburx\if@bbury% added 6/91 Rob Russell + \def\@p@sfile{#1}% + \fi\fi\fi\fi + \else\closein1 + \def\@p@sfile{\figurepath#1}% + \fi% + \else\closein1% + \def\@p@sfile{#1}% + \fi} + +\def\@p@@sbbllx#1{ + %\typeout{bbllx is #1} + \@bbllxtrue + \dimen100=#1 + \edef\@p@sbbllx{\number\dimen100} +} +\def\@p@@sbblly#1{ + %\typeout{bblly is #1} + \@bbllytrue + \dimen100=#1 + \edef\@p@sbblly{\number\dimen100} +} +\def\@p@@sbburx#1{ + %\typeout{bburx is #1} + \@bburxtrue + \dimen100=#1 + \edef\@p@sbburx{\number\dimen100} +} +\def\@p@@sbbury#1{ + %\typeout{bbury is #1} + \@bburytrue + \dimen100=#1 + \edef\@p@sbbury{\number\dimen100} +} +\def\@p@@sheight#1{ + \@heighttrue + \dimen100=#1 + \edef\@p@sheight{\number\dimen100} + %\typeout{Height is \@p@sheight} +} +\def\@p@@swidth#1{ + %\typeout{Width is #1} + \@widthtrue + \dimen100=#1 + \edef\@p@swidth{\number\dimen100} +} +\def\@p@@srheight#1{ + %\typeout{Reserved height is #1} + \@rheighttrue + \dimen100=#1 + \edef\@p@srheight{\number\dimen100} +} +\def\@p@@srwidth#1{ + %\typeout{Reserved width is #1} + \@rwidthtrue + \dimen100=#1 + \edef\@p@srwidth{\number\dimen100} +} +\def\@p@@sangle#1{ + %\typeout{Rotation is #1} + \@angletrue +% \dimen100=#1 + \edef\@p@sangle{#1} %\number\dimen100} +} +\def\@p@@ssilent#1{ + \@verbosefalse +} +\def\@p@@sprolog#1{\@prologfiletrue\def\@prologfileval{#1}} +\def\@p@@spostlog#1{\@postlogfiletrue\def\@postlogfileval{#1}} +\def\@cs@name#1{\csname #1\endcsname} +\def\@setparms#1=#2,{\@cs@name{@p@@s#1}{#2}} +% +% initialize the defaults (size the size of the figure) +% +\def\ps@init@parms{ + \@bbllxfalse \@bbllyfalse + \@bburxfalse \@bburyfalse + \@heightfalse \@widthfalse + \@rheightfalse \@rwidthfalse + \def\@p@sbbllx{}\def\@p@sbblly{} + \def\@p@sbburx{}\def\@p@sbbury{} + \def\@p@sheight{}\def\@p@swidth{} + \def\@p@srheight{}\def\@p@srwidth{} + \def\@p@sangle{0} + \def\@p@sfile{} + \def\@p@scost{10} + \def\@sc{} + \@prologfilefalse + \@postlogfilefalse + \@clipfalse + \if@noisy + \@verbosetrue + \else + \@verbosefalse + \fi +} +% +% Go through the options setting things up. +% +\def\parse@ps@parms#1{ + \@psdo\@psfiga:=#1\do + {\expandafter\@setparms\@psfiga,}} +% +% Compute bb height and width +% +\newif\ifno@bb +\def\bb@missing{ + \if@verbose{ + \typeout{psfig: searching \@p@sfile \space for bounding box} + }\fi + \no@bbtrue + \epsf@getbb{\@p@sfile} + \ifno@bb \else \bb@cull\epsf@llx\epsf@lly\epsf@urx\epsf@ury\fi +} +\def\bb@cull#1#2#3#4{ + \dimen100=#1 bp\edef\@p@sbbllx{\number\dimen100} + \dimen100=#2 bp\edef\@p@sbblly{\number\dimen100} + \dimen100=#3 bp\edef\@p@sbburx{\number\dimen100} + \dimen100=#4 bp\edef\@p@sbbury{\number\dimen100} + \no@bbfalse +} +% rotate point (#1,#2) about (0,0). +% The sine and cosine of the angle are already stored in \sine and +% \cosine. The result is placed in (\p@intvaluex, \p@intvaluey). +\newdimen\p@intvaluex +\newdimen\p@intvaluey +\def\rotate@#1#2{{\dimen0=#1 sp\dimen1=#2 sp +% calculate x' = x \cos\theta - y \sin\theta + \global\p@intvaluex=\cosine\dimen0 + \dimen3=\sine\dimen1 + \global\advance\p@intvaluex by -\dimen3 +% calculate y' = x \sin\theta + y \cos\theta + \global\p@intvaluey=\sine\dimen0 + \dimen3=\cosine\dimen1 + \global\advance\p@intvaluey by \dimen3 + }} +% rotate point (#1,#2) about the point (#3,#4), finding the x value. +% The sine and cosine of the angle are already stored in \sine and +% \cosine. The result is placed in \p@intvaluex +%\def\rotate@x#1#2#3#4{{\dimen0=#1 sp +% \dimen1=#2 sp +% \dimen2=#3 sp +% \dimen4=#4 sp +% \advance\dimen0 by -\dimen3 +% \dimen0=\cosine\dimen0 +% \advance\dimen4 by -\dimen2 +% \dimen4=\sine\dimen4 +% \global\p@intvaluex=\dimen0 +% \global\advance\p@intvaluex by \dimen4 +% \global\advance\p@intvaluex by \dimen3 +% +%}} +\def\compute@bb{ + \no@bbfalse + \if@bbllx \else \no@bbtrue \fi + \if@bblly \else \no@bbtrue \fi + \if@bburx \else \no@bbtrue \fi + \if@bbury \else \no@bbtrue \fi + \ifno@bb \bb@missing \fi + \ifno@bb \typeout{FATAL ERROR: no bb supplied or found} + \no-bb-error + \fi + % +%\typeout{BB: \@p@sbbllx, \@p@sbblly, \@p@sbburx, \@p@sbbury} + \if@angle + \Sine{\@p@sangle}\Cosine{\@p@sangle} + {\dimen100=\maxdimen\xdef\r@p@sbbllx{\number\dimen100} + \xdef\r@p@sbblly{\number\dimen100} + \xdef\r@p@sbburx{-\number\dimen100} + \xdef\r@p@sbbury{-\number\dimen100}} +% +% Need to rotate all four points and take the X-Y extremes of the new +% points as the new bounding box. + \def\minmaxtest{ + \ifnum\number\p@intvaluex<\r@p@sbbllx + \xdef\r@p@sbbllx{\number\p@intvaluex}\fi + \ifnum\number\p@intvaluex>\r@p@sbburx + \xdef\r@p@sbburx{\number\p@intvaluex}\fi + \ifnum\number\p@intvaluey<\r@p@sbblly + \xdef\r@p@sbblly{\number\p@intvaluey}\fi + \ifnum\number\p@intvaluey>\r@p@sbbury + \xdef\r@p@sbbury{\number\p@intvaluey}\fi + } +% lower left + \rotate@{\@p@sbbllx}{\@p@sbblly} + \minmaxtest +% upper left + \rotate@{\@p@sbbllx}{\@p@sbbury} + \minmaxtest +% lower right + \rotate@{\@p@sbburx}{\@p@sbblly} + \minmaxtest +% upper right + \rotate@{\@p@sbburx}{\@p@sbbury} + \minmaxtest + \edef\@p@sbbllx{\r@p@sbbllx}\edef\@p@sbblly{\r@p@sbblly} + \edef\@p@sbburx{\r@p@sbburx}\edef\@p@sbbury{\r@p@sbbury} +%\typeout{rotated BB: \r@p@sbbllx, \r@p@sbblly, \r@p@sbburx, \r@p@sbbury} + \fi + \count203=\@p@sbburx + \count204=\@p@sbbury + \advance\count203 by -\@p@sbbllx + \advance\count204 by -\@p@sbblly + \edef\@bbw{\number\count203} + \edef\@bbh{\number\count204} + %\typeout{ bbh = \@bbh, bbw = \@bbw } +} +% +% \in@hundreds performs #1 * (#2 / #3) correct to the hundreds, +% then leaves the result in @result +% +\def\in@hundreds#1#2#3{\count240=#2 \count241=#3 + \count100=\count240 % 100 is first digit #2/#3 + \divide\count100 by \count241 + \count101=\count100 + \multiply\count101 by \count241 + \advance\count240 by -\count101 + \multiply\count240 by 10 + \count101=\count240 %101 is second digit of #2/#3 + \divide\count101 by \count241 + \count102=\count101 + \multiply\count102 by \count241 + \advance\count240 by -\count102 + \multiply\count240 by 10 + \count102=\count240 % 102 is the third digit + \divide\count102 by \count241 + \count200=#1\count205=0 + \count201=\count200 + \multiply\count201 by \count100 + \advance\count205 by \count201 + \count201=\count200 + \divide\count201 by 10 + \multiply\count201 by \count101 + \advance\count205 by \count201 + % + \count201=\count200 + \divide\count201 by 100 + \multiply\count201 by \count102 + \advance\count205 by \count201 + % + \edef\@result{\number\count205} +} +\def\compute@wfromh{ + % computing : width = height * (bbw / bbh) + \in@hundreds{\@p@sheight}{\@bbw}{\@bbh} + %\typeout{ \@p@sheight * \@bbw / \@bbh, = \@result } + \edef\@p@swidth{\@result} + %\typeout{w from h: width is \@p@swidth} +} +\def\compute@hfromw{ + % computing : height = width * (bbh / bbw) + \in@hundreds{\@p@swidth}{\@bbh}{\@bbw} + %\typeout{ \@p@swidth * \@bbh / \@bbw = \@result } + \edef\@p@sheight{\@result} + %\typeout{h from w : height is \@p@sheight} +} +\def\compute@handw{ + \if@height + \if@width + \else + \compute@wfromh + \fi + \else + \if@width + \compute@hfromw + \else + \edef\@p@sheight{\@bbh} + \edef\@p@swidth{\@bbw} + \fi + \fi +} +\def\compute@resv{ + \if@rheight \else \edef\@p@srheight{\@p@sheight} \fi + \if@rwidth \else \edef\@p@srwidth{\@p@swidth} \fi + %\typeout{rheight = \@p@srheight, rwidth = \@p@srwidth} +} +% +% Compute any missing values +\def\compute@sizes{ + \compute@bb + \compute@handw + \compute@resv +} +% +% \psfig +% usage : \psfig{file=, height=, width=, bbllx=, bblly=, bburx=, bbury=, +% rheight=, rwidth=, clip=} +% +% "clip=" is a switch and takes no value, but the `=' must be present. +% +% The \leavevmode\hbox stuff makes this do the right thing for figures +% when the horizontal size is specified. + +\def\psfig#1{\leavevmode\hbox{\vbox { + % do a zero width hard space so that a single + % \psfig in a centering enviornment will behave nicely + %{\setbox0=\hbox{\ }\ \hskip-\wd0} + % + \ps@init@parms + \parse@ps@parms{#1} + \compute@sizes + % + \ifnum\@p@scost<\@psdraft{ + \if@verbose{ + \typeout{psfig: including \@p@sfile \space } + }\fi + % + \special{ps::[begin] \@p@swidth \space \@p@sheight \space + \@p@sbbllx \space \@p@sbblly \space + \@p@sbburx \space \@p@sbbury \space + startTexFig \space } + \if@angle + \special {ps:: \@p@sangle \space rotate \space} + \fi + \if@clip{ + \if@verbose{ + \typeout{(clip)} + }\fi + \special{ps:: doclip \space } + }\fi + \if@prologfile + \special{ps: plotfile \@prologfileval \space } \fi + \special{ps: plotfile \@p@sfile \space } + \if@postlogfile + \special{ps: plotfile \@postlogfileval \space } \fi + \special{ps::[end] endTexFig \space } + % Create the vbox to reserve the space for the figure + \vbox to \@p@srheight true sp{ + \hbox to \@p@srwidth true sp{ + \hss + } + \vss + } + }\else{ + % draft figure, just reserve the space and print the + % path name. + \if@draftbox{ + % Verbose draft: print file name in box + % NOTE: fbox is a LaTeX command! + \hbox{\fbox{\vbox to \@p@srheight true sp{ + \vss + \hbox to \@p@srwidth true sp{ \hss \@p@sfile \hss } + \vss + }}} + }\else{ + % Non-verbose draft + \vbox to \@p@srheight true sp{ + \vss + \hbox to \@p@srwidth true sp{\hss} + \vss + } + }\fi + + + + }\fi +}}} +\def\psglobal{\typeout{psfig: PSGLOBAL is OBSOLETE; use psprint -m instead}} +\psfigRestoreAt +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/quad.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,72 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Quadrature, Control Theory, Optimization, Top +@chapter Quadrature + +@menu +* Functions of one Variable:: +* Orthogonal Collocation:: +@end menu + +@node Functions of one Variable, Orthogonal Collocation, Quadrature, Quadrature +@section Functions of one Variable + +@ftable @code +@item quad + +@example +[v, ier, nfun] = quad ("f", a, b) +[v, ier, nfun] = quad ("f", a, b, tol) +[v, ier, nfun] = quad ("f", a, b, tol, sing) +@end example + +Integrate a nonlinear function of one variable using Quadpack. + +Where the first argument is the name of the function to call to +compute the value of the integrand. It must have the form + +@example +y = f (x) +@end example + +@noindent +where y and x are scalars. + +The second and third arguments are limits of integration. Either or +both may be infinite. + +The optional argument tol is a vector that specifies the desired +accuracy of the result. The first element of the vector is the desired +absolute tolerance, and the second element is the desired relative +tolerance. To choose a relative test only, set the absolute +tolerance to zero. To choose an absolute test only, set the relative +tolerance to zero. + +The optional argument @var{sing} is a vector of values at which the +integrand is singular. + +@findex quad_options +Tolerances and other options for @code{quad} may be specified using the +function @code{quad_options}. + +@end ftable + +@node Orthogonal Collocation, , Functions of one Variable, Quadrature +@section Orthogonal Collocation + +@ftable @code +@item colloc + +@example +[r, A, B, q] = colloc (n) +[r, A, B, q] = colloc (n, "left") +[r, A, B, q] = colloc (n, "left", "right") +@end example + +Compute derivative and integral weight matrices for orthogonal +collocation using the subroutines given in J. Villadsen and +M. L. Michelsen, @cite{Solution of Differential Equation Models by +Polynomial Approximation}. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/rd-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,8 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Readline Index, Info Index, Operator Index, Top +@unnumbered Readline Index + +@printindex rd
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/rluser.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,565 @@ +@comment %**start of header (This is for running Texinfo on a region.) +@c @setfilename rluser.info +@comment %**end of header (This is for running Texinfo on a region.) +@c @setchapternewpage odd + +@ignore +This file documents the end user interface to the GNU command line +editing features. It is to be an appendix to manuals for programs which +use these features. There is a document entitled "readline.texinfo" +which contains both end-user and programmer documentation for the GNU +Readline Library. + +Copyright (C) 1988 Free Software Foundation, Inc. + +Authored by Brian Fox. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@node Command Line Editing, Using Info, Trouble, Top +@appendix Command Line Editing + +This text describes GNU's command line editing interface. It is +relatively old and may not be entirely correct now. Please send a +message to @code{bug-octave@@bevo.che.wisc.edu} if you find any errors. +@xref{Reporting Bugs}, for more information about how to report bugs. + +@menu +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Bare Essentials:: +* Readline Movement Commands:: +* Readline Killing Commands:: +* Readline Arguments:: +* Readline Init File:: Customizing Readline from a user's view. +* Readline Init Syntax:: +* Readline Vi Mode:: +@end menu + +@node Introduction and Notation, Readline Interaction, Command Line Editing, Command Line Editing +@appendixsec Introduction to Line Editing + +The following paragraphs describe the notation we use to represent +keystrokes. + +The text @key{C-k} is read as `Control-K' and describes the character +produced when the Control key is depressed and the @key{k} key is struck. + +The text @key{M-k} is read as `Meta-K' and describes the character +produced when the meta key (if you have one) is depressed, and the @key{k} +key is struck. If you do not have a meta key, the identical keystroke +can be generated by typing @key{ESC} @i{first}, and then typing @key{k}. +Either process is known as @dfn{metafying} the @key{k} key. + +The text @key{M-C-k} is read as `Meta-Control-k' and describes the +character produced by @dfn{metafying} @key{C-k}. + +In addition, several keys have their own names. Specifically, +@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all +stand for themselves when seen in this text, or in an init file +(@pxref{Readline Init File}, for more info). + +@node Readline Interaction, Readline Bare Essentials, Introduction and Notation, Command Line Editing +@appendixsec Readline Interaction +@cindex interaction, readline + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press @key{RETURN}. You do not have to be at the +end of the line to press @key{RETURN}; the entire line is accepted +regardless of the location of the cursor within the line. + +@menu +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +@end menu + +@node Readline Bare Essentials, Readline Movement Commands, Readline Interaction, Command Line Editing +@appendixsec Readline Bare Essentials + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use @key{DEL} to +back up, and delete the mistyped character. + +Sometimes you may miss typing a character that you wanted to type, and +not notice your error until you have typed several other characters. In +that case, you can type @key{C-b} to move the cursor to the left, and then +correct your mistake. Afterwards, you can move the cursor to the right +with @key{C-f}. + +When you add text in the middle of a line, you will notice that characters +to the right of the cursor get `pushed over' to make room for the text +that you have inserted. Likewise, when you delete text behind the cursor, +characters to the right of the cursor get `pulled back' to fill in the +blank space created by the removal of the text. A list of the basic bare +essentials for editing the text of an input line follows. + +@table @asis +@item @key{C-b} +Move back one character. +@item @key{C-f} +Move forward one character. +@item @key{DEL} +Delete the character to the left of the cursor. +@item @key{C-d} +Delete the character underneath the cursor. +@item @w{Printing characters} +Insert itself into the line at the cursor. +@item @key{C-_} +Undo the last thing that you did. You can undo all the way back to an +empty line. +@end table + +@node Readline Movement Commands, Readline Killing Commands, Readline Bare Essentials, Command Line Editing +@appendixsec Readline Movement Commands + + +The above table describes the most basic possible keystrokes that you need +in order to do editing of the input line. For your convenience, many +other commands have been added in addition to @key{C-b}, @key{C-f}, +@key{C-d}, and @key{DEL}. Here are some commands for moving more rapidly +about the line. + +@table @key +@item C-a +Move to the start of the line. +@item C-e +Move to the end of the line. +@item M-f +Move forward a word. +@item M-b +Move backward a word. +@item C-l +Clear the screen, reprinting the current line at the top. +@end table + +Notice how @key{C-f} moves forward a character, while @key{M-f} moves +forward a word. It is a loose convention that control keystrokes +operate on characters while meta keystrokes operate on words. + +@node Readline Killing Commands, Readline Arguments, Readline Movement Commands, Command Line Editing +@appendixsec Readline Killing Commands + +@dfn{Killing} text means to delete the text from the line, but to save +it away for later use, usually by @dfn{yanking} it back into the line. +If the description for a command says that it `kills' text, then you can +be sure that you can get the text back in a different (or the same) +place later. + +Here is the list of commands for killing text. + +@table @key +@item C-k +Kill the text from the current cursor position to the end of the line. + +@item M-d +Kill from the cursor to the end of the current word, or if between +words, to the end of the next word. + +@item M-DEL +Kill from the cursor to the start of the previous word, or if between +words, to the start of the previous word. + +@item C-w +Kill from the cursor to the previous whitespace. This is different than +@key{M-DEL} because the word boundaries differ. + +@end table + +And, here is how to @dfn{yank} the text back into the line. Yanking +is + +@table @key +@item C-y +Yank the most recently killed text back into the buffer at the cursor. + +@item M-y +Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is @key{C-y} or @key{M-y}. +@end table + +When you use a kill command, the text is saved in a @dfn{kill-ring}. +Any number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it in one clean sweep. The kill +ring is not line specific; the text that you killed on a previously +typed line is available to be yanked back later, when you are typing +another line. + +@node Readline Arguments, Readline Init File, Readline Killing Commands, Command Line Editing +@appendixsec Readline Arguments + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the @i{sign} of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type @key{M--} @key{C-k}. + +The general way to pass numeric arguments to a command is to type meta +digits before the command. If the first `digit' you type is a minus +sign (@key{-}), then the sign of the argument will be negative. Once +you have typed one meta digit to get the argument started, you can type +the remainder of the digits, and then the command. For example, to give +the @key{C-d} command an argument of 10, you could type @key{M-1 0 C-d}. + + +@node Readline Init File, Readline Init Syntax, Readline Arguments, Command Line Editing +@appendixsec Readline Init File + +Although the Readline library comes with a set of Emacs-like +keybindings, it is possible that you would like to use a different set +of keybindings. You can customize programs that use Readline by putting +commands in an @dfn{init} file in your home directory. The name of this +file is @file{~/.inputrc}. + +When a program which uses the Readline library starts up, the +@file{~/.inputrc} file is read, and the keybindings are set. + +In addition, the @key{C-x C-r} command re-reads this init file, thus +incorporating any changes that you might have made to it. + +@menu +* Readline Init Syntax:: Syntax for the commands in @file{~/.inputrc}. +* Readline Vi Mode:: Switching to @code{vi} mode in Readline. +@end menu + +@node Readline Init Syntax, Readline Vi Mode, Readline Init File, Command Line Editing +@appendixsec Readline Init Syntax + +There are only four constructs allowed in the @file{~/.inputrc} +file: + +@table @asis +@item Variable Settings +You can change the state of a few variables in Readline. You do this by +using the @code{set} command within the init file. Here is how you +would specify that you wish to use Vi line editing commands: + +@example +set editing-mode vi +@end example + +Right now, there are only a few variables which can be set; so few in +fact, that we just iterate them here: + +@table @code + +@item editing-mode +@vindex editing-mode +The @code{editing-mode} variable controls which editing mode you are +using. By default, GNU Readline starts up in Emacs editing mode, where +the keystrokes are most similar to Emacs. This variable can either be +set to @code{emacs} or @code{vi}. + +@item horizontal-scroll-mode +@vindex horizontal-scroll-mode +This variable can either be set to @code{On} or @code{Off}. Setting it +to @code{On} means that the text of the lines that you edit will scroll +horizontally on a single screen line when they are larger than the width +of the screen, instead of wrapping onto a new screen line. By default, +this variable is set to @code{Off}. + +@item mark-modified-lines +@vindex mark-modified-lines +This variable when set to @code{On}, says to display an asterisk +(@samp{*}) at the starts of history lines which have been modified. +This variable is off by default. + +@item prefer-visible-bell +@vindex prefer-visible-bell +If this variable is set to @code{On} it means to use a visible bell if +one is available, rather than simply ringing the terminal bell. By +default, the value is @code{Off}. +@end table + +@item Key Bindings +The syntax for controlling keybindings in the @file{~/.inputrc} file is +simple. First you have to know the @i{name} of the command that you +want to change. The following pages contain tables of the command name, +the default keybinding, and a short description of what the command +does. + +Once you know the name of the command, simply place the name of the key +you wish to bind the command to, a colon, and then the name of the +command on a line in the @file{~/.inputrc} file. The name of the key +can be expressed in different ways, depending on which is most +comfortable for you. + +@table @asis +@item @w{@var{keyname}: @var{function-name} or @var{macro}} +@var{keyname} is the name of a key spelled out in English. For example: +@example +Control-u: universal-argument +Meta-Rubout: backward-kill-word +Control-o: ">&output" +@end example + +In the above example, @key{C-u} is bound to the function +@code{universal-argument}, and @key{C-o} is bound to run the macro +expressed on the right hand side (that is, to insert the text +@samp{>&output} into the line). + +@item @w{"@var{keyseq}": @var{function-name} or @var{macro}} +@var{keyseq} differs from @var{keyname} above in that strings denoting +an entire key sequence can be specified. Simply place the key sequence +in double quotes. GNU Emacs style key escapes can be used, as in the +following example: + +@example +"\C-u": universal-argument +"\C-x\C-r": re-read-init-file +"\e[11~": "Function Key 1" +@end example + +In the above example, @key{C-u} is bound to the function +@code{universal-argument} (just as it was in the first example), +@key{C-x C-r} is bound to the function @code{re-read-init-file}, and +@key{ESC [ 1 1 ~} is bound to insert the text @samp{Function Key 1}. + +@end table +@end table + +@menu +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Miscellaneous Commands:: Other miscellaneous commands. +@end menu + +@node Commands For Moving, Commands For History, Readline Init Syntax, Readline Init Syntax +@appendixsubsec Commands For Moving +@ftable @code +@item beginning-of-line (@key{C-a}) +Move to the start of the current line. + +@item end-of-line (@key{C-e}) +Move to the end of the line. + +@item forward-char (@key{C-f}) +Move forward a character. + +@item backward-char (@key{C-b}) +Move back a character. + +@item forward-word (@key{M-f}) +Move forward to the end of the next word. + +@item backward-word (@key{M-b}) +Move back to the start of this, or the previous, word. + +@item clear-screen (@key{C-l}) +Clear the screen leaving the current line at the top of the screen. + +@end ftable + +@node Commands For History, Commands For Text, Commands For Moving, Readline Init Syntax +@appendixsubsec Commands For Manipulating The History + +@ftable @code +@item accept-line (Newline, Return) +Accept the line regardless of where the cursor is. If this line is +non-empty, add it to the history list. If this line was a history +line, then restore the history line to its original state. + +@item previous-history (@key{C-p}) +Move `up' through the history list. + +@item next-history (@key{C-n}) +Move `down' through the history list. + +@item beginning-of-history (@key{M-<}) +Move to the first line in the history. + +@item end-of-history (@key{M->}) +Move to the end of the input history, i.e., the line you are entering! + +@item reverse-search-history (@key{C-r}) +Search backward starting at the current line and moving `up' through +the history as necessary. This is an incremental search. + +@item forward-search-history (@key{C-s}) +Search forward starting at the current line and moving `down' through +the the history as necessary. + +@end ftable + +@node Commands For Text, Commands For Killing, Commands For History, Readline Init Syntax +@appendixsubsec Commands For Changing Text + +@ftable @code +@item delete-char (@key{C-d}) +Delete the character under the cursor. If the cursor is at the +beginning of the line, and there are no characters in the line, and +the last character typed was not @key{C-d}, then return EOF. + +@item backward-delete-char (Rubout) +Delete the character behind the cursor. A numeric arg says to kill +the characters instead of deleting them. + +@item quoted-insert (@key{C-q}, @key{C-v}) +Add the next character that you type to the line verbatim. This is +how to insert things like @key{C-q} for example. + +@item tab-insert (@key{M-TAB}) +Insert a tab character. + +@item self-insert (a, b, A, 1, !, ...) +Insert yourself. + +@item transpose-chars (@key{C-t}) +Drag the character before point forward over the character at point. +Point moves forward as well. If point is at the end of the line, then +transpose the two characters before point. Negative args don't work. + +@item transpose-words (@key{M-t}) +Drag the word behind the cursor past the word in front of the cursor +moving the cursor over that word as well. + +@item upcase-word (@key{M-u}) +Uppercase the current (or following) word. With a negative argument, +do the previous word, but do not move point. + +@item downcase-word (@key{M-l}) +Lowercase the current (or following) word. With a negative argument, +do the previous word, but do not move point. + +@item capitalize-word (@key{M-c}) +Uppercase the current (or following) word. With a negative argument, +do the previous word, but do not move point. + +@end ftable + +@node Commands For Killing, Numeric Arguments, Commands For Text, Readline Init Syntax +@appendixsubsec Killing And Yanking + +@ftable @code + +@item kill-line (@key{C-k}) +Kill the text from the current cursor position to the end of the line. + +@item backward-kill-line () +Kill backward to the beginning of the line. This is normally unbound. + +@item kill-word (@key{M-d}) +Kill from the cursor to the end of the current word, or if between +words, to the end of the next word. + +@item backward-kill-word (@key{M-DEL}) +Kill the word behind the cursor. + +@item unix-line-discard (@key{C-u}) +Do what @key{C-u} used to do in Unix line input. We save the killed text on +the kill-ring, though. + +@item unix-word-rubout (@key{C-w}) +Do what @key{C-w} used to do in Unix line input. The killed text is saved +on the kill-ring. This is different than backward-kill-word because +the word boundaries differ. + +@item yank (@key{C-y}) +Yank the top of the kill ring into the buffer at point. + +@item yank-pop (@key{M-y}) +Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is yank or yank-pop. +@end ftable + +@node Numeric Arguments, Commands For Completion, Commands For Killing, Readline Init Syntax +@appendixsubsec Specifying Numeric Arguments +@ftable @code + +@item digit-argument (@key{M-0}, @key{M-1}, ... @key{M--}) +Add this digit to the argument already accumulating, or start a new +argument. @key{M--} starts a negative argument. + +@item universal-argument () +Do what @key{C-u} does in emacs. By default, this is not bound. +@end ftable + + +@node Commands For Completion, Miscellaneous Commands, Numeric Arguments, Readline Init Syntax +@appendixsubsec Letting Readline Type For You + +@ftable @code +@item complete (TAB) +Attempt to do completion on the text before point. This is +implementation defined. Generally, if you are typing a file name +argument, you can do file name completion; if you are typing a command, +you can do command completion, if you are typing in a symbol to GDB, you +can do symbol name completion, if you are typing in a variable to Bash, +you can do variable name completion... + +@item possible-completions (M-?) +List the possible completions of the text before point. +@end ftable + +@node Miscellaneous Commands, , Commands For Completion, Readline Init Syntax +@appendixsubsec Some Miscellaneous Commands +@ftable @code + +@item re-read-init-file (@key{C-x} @key{C-r}) +Read in the contents of your @file{~/.inputrc} file, and incorporate +any bindings found there. + +@item abort (@key{C-g}) +Ding! Stops things. + +@item do-uppercase-version (@key{M-a}, @key{M-b}, ...) +Run the command that is bound to your uppercase brother. + +@item prefix-meta (ESC) +Make the next character that you type be metafied. This is for people +without a meta key. Typing @key{ESC f} is equivalent to typing +@key{M-f}. + +@item undo (@key{C-_}) +Incremental undo, separately remembered for each line. + +@item revert-line (@key{M-r}) +Undo all changes made to this line. This is like typing the `undo' +command enough times to get back to the beginning. +@end ftable + +@node Readline Vi Mode, , Readline Init Syntax, Command Line Editing +@appendixsec Readline Vi Mode + +While the Readline library does not have a full set of Vi editing +functions, it does contain enough to allow simple editing of the line. + +In order to switch interactively between Emacs and Vi editing modes, use +the command @key{M-C-j} (toggle-editing-mode). + +When you enter a line in Vi mode, you are already placed in `insertion' +mode, as if you had typed an `i'. Pressing @key{ESC} switches you into +`edit' mode, where you can edit the text of the line with the standard +Vi movement keys, move to previous history lines with `k', and following +lines with `j', and so forth. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/set.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,27 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Sets, Statistics, Signal Processing, Top +@chapter Sets + +Octave has a limited set of functions for managing sets of data, where a +set is defined as a collection unique elements. + +@findex create_set +Given a matrix or vector of values, the function @code{create_set} +returns a row vector containing unique values, sorted in ascending +order. For example, @samp{create_set ([1, 2; 3, 4; 4, 2])} returns +the vector @samp{[1, 2, 3, 4]}. + +@findex union +@findex intersection +The functions @code{union} and @code{intersection} take two sets as +arguments and return the union and interection, respectively. For +example, @samp{union ([1, 2, 3], [2, 3, 5])} returns the vector +@samp{[1, 2, 5]}. + +@findex complement +The function @code{complement (@var{a}, @var{b})} returns the elements +of set @var{b} that are not in set @var{a}. For example, +@samp{complement ([1, 2, 3], [2, 3, 5])} returns the value @samp{5}.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/signal.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,213 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Signal Processing, Sets, Control Theory, Top +@chapter Signal Processing + +I hope that someday Octave will include more signal processing +functions. If you would like to help improve Octave in this area, +please contact @code{bug-octave@@bevo.che.wisc.edu}. + +@ftable @code +@item fft (@var{a} [, @var{n}]) +Compute the FFT of @var{a} using subroutines from FFTPACK. If @var{a} +is a matrix, @code{fft} computes the FFT for each column of @var{a}. + +If called with two arguments, @var{n} is expected to be an integer +specifying the number of elements of @var{a} to use. If @var{a} is a +matrix, @var{n} specifies the number of rows of @var{a} to use. If +@var{n} is larger than the size of @var{a}, @var{a} is resized and +padded with zeros. + +@item fft2 (@var{a} [, @var{n} [, @var{m}]]) +Compute the two dimensional FFT of @var{a}. + +The optional arguments @var{n} and @var{m} may be used specify the +number of rows and columns of @var{a} to use. If either of these is +larger than the size of @var{a}, @var{a} is resized and padded with +zeros. + +@item fftconv (@var{a}, @var{b}, @var{N}) +This function returns the convolution of the vectors @var{a} and +@var{b}, a vector with length equal to the @code{length (a) + length (b) +- 1}. If @var{a} and @var{b} are the coefficient vectors of two +polynomials, the returned value is the coefficient vector of the product +polynomial. + +The computation uses the FFT by calling the function @code{fftfilt}. If +the optional argument @var{N} is specified, an N-point FFT is used. + +@item fftfilt (@var{b}, @var{x}, @var{N}) + +With two arguments, @code{fftfilt} filters @var{x} with the FIR filter +@var{b} using the FFT. + +Given the optional third argument, @var{N}, @code{fftfilt} uses the +overlap-add method to filter @var{x} with @var{b} using an N-point FFT. + +@item filter (@var{b}, @var{a}, @var{x}) +This function returns the solution to the following linear, +time-invariant difference equation: +@iftex +@tex +$$ +\sum_{k=0}^N a_{k+1} y_{n-k} = \sum_{k=0}^M b_{k+1} x_{n-k}, \qquad + 1 \le n \le P +$$ +@end tex +@end iftex +@ifinfo + +@smallexample + N M + SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k) for 1<=n<=length(x) + k=0 k=0 +@end smallexample +@end ifinfo + +@noindent +where +@ifinfo + N=length(a)-1 and M=length(b)-1. +@end ifinfo +@iftex +@tex + $a \in \Re^{N-1}$, $b \in \Re^{M-1}$, and $x \in \Re^P$. +@end tex +@end iftex +An equivalent form of this equation is: +@iftex +@tex +$$ +y_n = -\sum_{k=1}^N c_{k+1} y_{n-k} + \sum_{k=0}^M d_{k+1} x_{n-k}, \qquad + 1 \le n \le P +$$ +@end tex +@end iftex +@ifinfo + +@smallexample + N M + y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k) for 1<=n<=length(x) + k=1 k=0 +@end smallexample +@end ifinfo + +@noindent +where +@ifinfo + c = a/a(1) and d = b/a(1). +@end ifinfo +@iftex +@tex +$c = a/a_1$ and $d = b/a_1$. +@end tex +@end iftex + +In terms of the z-transform, y is the result of passing the discrete- +time signal x through a system characterized by the following rational +system function: +@iftex +@tex +$$ +H(z) = {\sum_{k=0}^M d_{k+1} z^{-k} \over 1 + \sum_{k+1}^N c_{k+1} z^{-k}} +$$ +@end tex +@end iftex +@ifinfo + +@example + M + SUM d(k+1) z^(-k) + k=0 + H(z) = ---------------------- + N + 1 + SUM c(k+1) z(-k) + k=1 +@end example +@end ifinfo + +When called as + +@example +[y, sf] = filter (b, a, x, si) +@end example + +@noindent +@code{filter} uses the argument @var{si} as the initial state of the +system and and returns the final state in @var{sf}. The state vector is +a column vector whose length is equal to the length of the longest +coefficient vector minus one. If @var{si} is not set, the initial state +vector is set to all zeros. + +@item freqz +Compute the frequency response of a filter. + +@code{[@var{h}, @var{w}] = freqz (@var{b})} returns the complex frequency +response @var{h} of the FIR filter with coefficients @var{b}. The +response is evaluated at 512 angular frequencies between 0 and +@ifinfo + pi. +@end ifinfo +@iftex +@tex + $\pi$. +@end tex +@end iftex + +@noindent +The output value @var{w} is a vector containing the 512 frequencies. + +@code{[@var{h}, @var{w}] = freqz (@var{b}, @var{a})} returns the complex +frequency response of the rational IIR filter whose numerator has +coefficients @var{b} and denominator coefficients @var{a}. + + +@code{[@var{h}, @var{w}] = freqz (@var{b}, @var{a}, @var{n})} returns the +response evaluated at @var{n} angular frequencies. For fastest +computation n should factor into a small number of small primes. + + +@code{[@var{h}, @var{w}] = freqz (@var{b}, @var{a}, @var{n}, "whole")} +evaluates the response at n frequencies between 0 and +@ifinfo + 2*pi. +@end ifinfo +@iftex +@tex + $2\pi$. +@end tex +@end iftex + +@item ifft (@var{a} [, @var{n}]) +Compute the inverse FFT of @var{a} using subroutines from FFTPACK. If +@var{a} is a matrix, @code{fft} computes the inverse FFT for each column +of @var{a}. + +If called with two arguments, @var{n} is expected to be an integer +specifying the number of elements of @var{a} to use. If @var{a} is a +matrix, @var{n} specifies the number of rows of @var{a} to use. If +@var{n} is larger than the size of @var{a}, @var{a} is resized and +padded with zeros. + +@item ifft2 (@var{a} [, @var{n} [, @var{m}]]) +Compute the two dimensional inverse FFT of @var{a}. + +The optional arguments @var{n} and @var{m} may be used specify the +number of rows and columns of @var{a} to use. If either of these is +larger than the size of @var{a}, @var{a} is resized and padded with +zeros. + +@item sinc (@var{x}) +Returns +@iftex +@tex +$ \sin (\pi x)/(\pi x)$. +@end tex +@end iftex +@ifinfo + sin(pi*x)/(pi*x). +@end ifinfo + +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/special.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,334 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Special Matrices, Matrix Manipulation, Input and Output, Top +@chapter Special Matrices + +Octave provides a number of functions for creating special matrix forms. +In nearly all cases, it is best to use the built-in functions for this +purpose than to try to use other tricks to achieve the same effect. + +@menu +* Special Utility Matrices:: +* Famous Matrices:: +@end menu + +@node Special Utility Matrices, Famous Matrices, Special Matrices, Special Matrices +@section Special Utility Matrices + +@findex eye + +The function @code{eye} returns an identity matrix. If invoked with a +single scalar argument, @code{eye} returns a square matrix with the +dimension specified. If you supply two scalar arguments, @code{eye} +takes them to be the number of rows and columns. If given a matrix or +vector argument, @code{eye} returns an identity matrix with the same +dimensions as the given argument. + +For example, + +@example +eye (3) +@end example + +@noindent +creates an identity matrix with three rows and three columns, + +@example +eye (5, 8) +@end example + +@noindent +creates an identity matrix with five rows and eight columns, and + +@example +eye ([13, 21; 34, 55]) +@end example + +@noindent +creates an identity matrix with two rows and two columns. + +Normally, @code{eye} expects any scalar arguments you provide to be real +and non-negative. The variables @code{ok_to_lose_imaginary_part} and +@code{treat_neg_dim_as_zero} control the behavior of @code{eye} for +complex and negative arguments. @xref{User Preferences}. Any +non-integer arguments are rounded to the nearest integer value. + +There is an ambiguity when these functions are called with a single +argument. You may have intended to create a matrix with the same +dimensions as another variable, but ended up with something quite +different, because the variable that you used as an argument was a +scalar instead of a matrix. + +For example, if you need to create an identity matrix with the same +dimensions as another variable in your program, it is best to use code +like this + +@example +eye (rows (a), columns (a)) +@end example + +@noindent +instead of just + +@example +eye (a) +@end example + +@noindent +unless you know that the variable @var{a} will @emph{always} be a matrix. + +@findex ones +@findex zeros +@findex rand + +The functions @code{ones}, @code{zeros}, and @code{rand} all work like +@code{eye}, except that they fill the resulting matrix with all ones, +all zeros, or a set of random values. + +If you need to create a matrix whose values are all the same, you should +use an expression like + +@example +val_matrix = val * ones (n, m) +@end example + +The @code{rand} function also takes some additional arguments that allow +you to control its behavior. For example, the function call + +@example +rand ("normal") +@end example + +@noindent +causes the sequence of numbers to be normally distributed. You may also +use an argument of @code{"uniform"} to select a uniform distribution. To +find out what the current distribution is, use an argument of +@code{"dist"}. + +Normally, @code{rand} obtains the seed from the system clock, so that +the sequence of random numbers is not the same each time you run Octave. +If you really do need for to reproduce a sequence of numbers exactly, +you can set the seed to a specific value. For example, the function call + +@example +rand ("seed", 13) +@end example + +@noindent +sets the seed to the number 13. To see what the current seed is, use +the argument @code{"seed"}. + +If it is invoked without arguments, @code{rand} returns a +single element of a random sequence. + +The @code{rand} function uses Fortran code from RANLIB, a library +of fortran routines for random number generation, compiled by Barry W. +Brown and James Lovato of the Department of Biomathematics at The +University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030. + +@findex diag + +To create a diagonal matrix with vector @var{v} on diagonal @var{k}, use +the function diag (@var{v}, @var{k}). The second argument is optional. +If it is positive, the vector is placed on the @var{k}-th +super-diagonal. If it is negative, it is placed on the @var{-k}-th +sub-diagonal. The default value of @var{k} is 0, and the vector is +placed on the main diagonal. For example, + +@example +octave:13> diag ([1, 2, 3], 1) +ans = + + 0 1 0 0 + 0 0 2 0 + 0 0 0 3 + 0 0 0 0 +@end example + +@findex linspace +@findex logspace + +The functions @code{linspace} and @code{logspace} make it very easy to +create vectors with evenly or logarithmically spaced elements. For +example, + +@example +linspace (@var{base}, @var{limit}, @var{n}) +@end example + +@noindent +creates a row vector with @var{n} (@var{n} greater than 2) linearly +spaced elements between @var{base} and @var{limit}. The @var{base} and +@var{limit} are always included in the range. If @var{base} is greater +than @var{limit}, the elements are stored in decreasing order. If the +number of points is not specified, a value of 100 is used. + +The function @code{logspace} is similar to @code{linspace} except that +the values are logarithmically spaced. + +If @var{limit} is equal to +@iftex +@tex +$\pi$, +@end tex +@end iftex +@ifinfo +pi, +@end ifinfo +the points are between +@iftex +@tex +$10^{base}$ and $\pi$, +@end tex +@end iftex +@ifinfo +10^base and pi, +@end ifinfo +@emph{not} +@iftex +@tex +$10^{base}$ and $10^{\pi}$, +@end tex +@end iftex +@ifinfo +10^base and 10^pi, +@end ifinfo +in order to be compatible with the corresponding @sc{Matlab} function. + +The @code{linspace} and @code{logspace} functions always return row +vectors, regardless of the value of @code{prefer_column_vectors}. +@xref{Ranges}. + +@node Famous Matrices, , Special Utility Matrices, Special Matrices +@section Famous Matrices + +The following functions return famous matrix forms. + +@ftable @code +@item hadamard (@var{k}) +Return the Hadamard matrix of order n = 2^k. + +@item hankel (@var{c}, @var{r}) +Return the Hankel matrix constructed given the first column @var{c}, and +(optionally) the last row @var{r}. If the last element of @var{c} is +not the same as the first element of @var{r}, the last element of +@var{c} is used. If the second argument is omitted, the last row is +taken to be the same as the first column. + +A Hankel matrix formed from an m-vector @var{c}, and an n-vector +@var{r}, has the elements +@iftex +@tex +$$ +H (i, j) = \cases{c_{i+j-1},&$i+j-1\le m$;\cr r_{i+j-m},&otherwise.\cr} +$$ +@end tex +@end iftex +@ifinfo + +@example +@group +H (i, j) = c (i+j-1), i+j-1 <= m; +H (i, j) = r (i+j-m), otherwise +@end group +@end example + +@end ifinfo + +@item hilb (@var{n}) +Return the Hilbert matrix of order @var{n}. The +@iftex +@tex +$i,\,j$ +@end tex +@end iftex +@ifinfo +i, j +@end ifinfo +element of a Hilbert matrix is defined as +@iftex +@tex +$$ +H (i, j) = {1 \over (i + j - 1)} +$$ +@end tex +@end iftex +@ifinfo + +@example +H (i, j) = 1 / (i + j - 1) +@end example +@end ifinfo + +@item invhilb (@var{n}) +Return the inverse of a Hilbert matrix of order @var{n}. This is exact. +Compare with the numerical calculation of @code{inverse (hilb (n))}, +which suffers from the ill-conditioning of the Hilbert matrix, and the +finite precision of your computer's floating point arithmetic. + +@item toeplitz (@var{c}, @var{r}) +Return the Toeplitz matrix constructed given the first column @var{c}, +and (optionally) the first row @var{r}. If the first element of @var{c} +is not the same as the first element of @var{r}, the first element of +@var{c} is used. If the second argument is omitted, the first row is +taken to be the same as the first column. + +A square Toeplitz matrix has the form +@iftex +@tex +$$ +\left[\matrix{c_0 & r_1 & r_2 & \ldots & r_n\cr + c_1 & c_0 & r_1 & & c_{n-1}\cr + c_2 & c_1 & c_0 & & c_{n-2}\cr + \vdots & & & & \vdots\cr + c_n & c_{n-1} & c_{n-2} & \ldots & c_0}\right]. +$$ +@end tex +@end iftex +@ifinfo + +@example +@group +c(0) r(1) r(2) ... r(n) +c(1) c(0) r(1) r(n-1) +c(2) c(1) c(0) r(n-2) + . . + . . + . . + +c(n) c(n-1) c(n-2) ... c(0) +@end group +@end example +@end ifinfo + +@item vander (@var{c}) +Return the Vandermonde matrix whose next to last column is @var{c}. + +A Vandermonde matrix has the form +@iftex +@tex +$$ +\left[\matrix{c_0^n & \ldots & c_0^2 & c_0 & 1\cr + c_1^n & \ldots & c_1^2 & c_1 & 1\cr + \vdots & & \vdots & \vdots & \vdots\cr + c_n^n & \ldots & c_n^2 & c_n & 1}\right]. +$$ +@end tex +@end iftex +@ifinfo + +@example +@group +c(0)^n ... c(0)^2 c(0) 1 +c(1)^n ... c(1)^2 c(1) 1 + . . . . + . . . . + . . . . + +c(n)^n ... c(n)^2 c(n) 1 +@end group +@end example +@end ifinfo +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/stats.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,68 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Statistics, Plotting, Sets, Top +@chapter Statistics + +I hope that someday Octave will include more statistics functions. If +you would like to help improve Octave in this area, please contact +@code{bug-octave@@bevo.che.wisc.edu}. + +@ftable @code +@item corrcoef (@var{x} [, @var{y}]) +If each row of @var{x} and @var{y} is an observation and each column is +a variable, the (@var{i},@var{j})-th entry of +@code{corrcoef (@var{x}, @var{y})} is the correlation between the +@var{i}-th variable in @var{x} and the @var{j}-th variable in @var{y}. +If invoked with one argument, compute @code{corrcoef (@var{x}, @var{x})}. + +@item cov (@var{x} [, @var{y}]) +If each row of @var{x} and @var{y} is an observation and each column is +a variable, the (@var{i},@var{j})-th entry of +@code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th +variable in @var{x} and the @var{j}-th variable in @var{y}. If invoked +with one argument, compute @code{cov (@var{x}, @var{x})}. + +@item kurtosis (@var{x}) +If @var{x} is a vector of length @var{N}, return the kurtosis + +@example +kurtosis(x) = N^(-1) std(x)^(-4) SUM_i (x(i)-mean(x))^4 - 3 +@end example + +@noindent +of @var{x}. If @var{x} is a matrix, return the row vector containing +the kurtosis of each column. + +@item mahalanobis (@var{x}, @var{y}) +Returns Mahalanobis' D-square distance between the multivariate samples +@var{x} and @var{y}, which must have the same number of components +(columns), but may have a different number of observations (rows). + +@item mean (@var{a}) +If @var{a} is a vector, compute the mean of the elements of @var{a}. If +@var{a} is a matrix, compute the mean for each column and return them in +a row vector. + +@item median (@var{a}) +If @var{a} is a vector, compute the median value of the elements of +@var{a}. If @var{a} is a matrix, compute the median value for each +column and return them in a row vector. + +@item skewness (@var{x}) +If @var{x} is a vector of length @var{N}, return the skewness + +@example +skewness (x) = N^(-1) std(x)^(-3) SUM_i (x(i)-mean(x))^3 +@end example + +@noindent +of @var{x}. If @var{x} is a matrix, return the row vector containing +the skewness of each column. + +@item std (@var{a}) +If @var{a} is a vector, compute the standard deviation of the elements +of @var{a}. If @var{a} is a matrix, compute the standard deviation for +each column and return them in a row vector. +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/stmt.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,543 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Statements, Functions and Scripts, Expressions, Top +@chapter Statements +@cindex statements + +@dfn{Control statements} such as @code{if}, @code{while}, and so on +control the flow of execution in Octave programs. All the control +statements start with special keywords such as @code{if} and +@code{while}, to distinguish them from simple expressions. + +@cindex @code{end} statement +Many control statements contain other statements; for example, the +@code{if} statement contains another statement which may or may not be +executed. Each control statement has a corresponding @dfn{end} +statement that marks the end of the end of the control statement. For +example, the keyword @code{endif} marks the end of an @code{if} +statement, and @code{endwhile} marks the end of a @code{while} +statement. You can use the keyword @code{end} anywhere a more specific +end keyword is expected, but using the more specific keywords is +preferred because if you use them, Octave is able to provide better +diagnostics for mismatched or missing end tokens. + +The list of statements contained between keywords like @code{if} or +@code{while} and the corresponding end statement is called the +@dfn{body} of a control statement. + +@menu +* The if Statement:: +* The while Statement:: +* The for Statement:: +* The break Statement:: +* The continue Statement:: +* The unwind_protect Statement:: +* The try Statement:: +* Continuation Lines:: +@end menu + +@node The if Statement, The while Statement, Statements, Statements +@section The @code{if} Statement +@cindex @code{if} statement +@cindex @code{else} statement +@cindex @code{elseif} statement +@cindex @code{endif} statement + +The @code{if} statement is Octave's decision-making statement. There +are three basic forms of an @code{if} statement. In its simplest form, +it looks like this: + +@example +if (@var{condition}) @var{then-body} endif +@end example + +@noindent +@var{condition} is an expression that controls what the rest of the +statement will do. The @var{then-body} is executed only if +@var{condition} is true. + +The condition in an @code{if} statement is considered true if its value +is non-zero, and false if its value is zero. If the value of the +conditional expression in an @code{if} statement is a vector or a +matrix, it is considered true only if @emph{all} of the elements are +non-zero. + +The second form of an if statement looks like this: + +@example +if (@var{condition}) @var{then-body} else @var{else-body} endif +@end example + +@noindent +If @var{condition} is true, @var{then-body} is executed; otherwise, +@var{else-body} is executed. + +Here is an example: + +@example +@group +if (rem (x, 2) == 0) + printf ("x is even\n"); +else + printf ("x is odd\n"); +endif +@end group +@end example + +In this example, if the expression @code{rem (x, 2) == 0} is true (that +is, the value of @code{x} is divisible by 2), then the first +@code{printf} statement is evaluated, otherwise the second @code{printf} +statement is evaluated. + +The third and most general form of the @code{if} statement allows +multiple decisions to be combined in a single statement. It looks like +this: + +@example +if (@var{condition}) @var{then-body} elseif (@var{condition}) @var{elseif-body} else @var{else-body} endif +@end example + +@noindent +Any number of @code{elseif} clauses may appear. Each condition is +tested in turn, and if one is found to be true, its corresponding +@var{body} is executed. If none of the conditions are true and the +@code{else} clause is present, its body is executed. Only one +@code{else} clause may appear, and it must be the last part of the +satement. + +In the following example, if the first condition is true (that is, the +value of @code{x} is divisible by 2), then the first @code{printf} +statement is executed. If it is false, then the second condition is +tested, and if it is true (that is, the value of @code{x} is divisible +by 3), then the second @code{printf} statement is executed. Otherwise, +the third @code{printf} statement is performed. + +@example +@group +if (rem (x, 2) == 0) + printf ("x is even\n"); +elseif (rem (x, 3) == 0) + printf ("x is odd and divisible by 3\n"); +else + printf ("x is odd\n"); +endif +@end group +@end example + +Note that the @code{elseif} keyword must not be spelled @code{else if}, +as is allowed in Fortran. If it is, the space between the @code{else} +and @code{if} will tell Octave to treat this as a new @code{if} +statement within another @code{if} statement's @code{else} clause. For +example, if you write + +@example +@group +if (@var{c1}) + @var{body-1} +else if (@var{c2}) + @var{body-2} +endif +@end group +@end example + +@noindent +Octave will expect additional input to complete the first @code{if} +statement. If you are using Octave interactively, it will continue to +prompt you for additional input. If Octave is reading this input from a +file, it may complain about missing or mismatched @code{end} statements, +or, if you have not used the more specific @code{end} statements +(@code{endif}, @code{endfor}, etc.), it may simply produce incorrect +results, without producing any warning messages. + +It is much easier to see the error if we rewrite the statements above +like this, + +@example +@group +if (@var{c1}) + @var{body-1} +else + if (@var{c2}) + @var{body-2} + endif +@end group +@end example + +@noindent +using the indentation to show how Octave groups the statements. +@xref{Functions and Scripts}. + +@node The while Statement, The for Statement, The if Statement, Statements +@section The @code{while} Statement +@cindex @code{while} statement +@cindex @code{endwhile} statement +@cindex loop +@cindex body of a loop + +In programming, a @dfn{loop} means a part of a program that is (or at least can +be) executed two or more times in succession. + +The @code{while} statement is the simplest looping statement in Octave. +It repeatedly executes a statement as long as a condition is true. As +with the condition in an @code{if} statement, the condition in a +@code{while} statement is considered true if its value is non-zero, and +false if its value is zero. If the value of the conditional expression +in an @code{if} statement is a vector or a matrix, it is considered true +only if @emph{all} of the elements are non-zero. + +Octave's @code{while} statement looks like this: + +@example +@group +while (@var{condition}) + @var{body} +endwhile +@end group +@end example + +@noindent +Here @var{body} is a statement or list of statements that we call the +@dfn{body} of the loop, and @var{condition} is an expression that +controls how long the loop keeps running. + +The first thing the @code{while} statement does is test @var{condition}. +If @var{condition} is true, it executes the statement @var{body}. After +@var{body} has been executed, @var{condition} is tested again, and if it +is still true, @var{body} is executed again. This process repeats until +@var{condition} is no longer true. If @var{condition} is initially +false, the body of the loop is never executed. + +This example creates a variable @code{fib} that contains the elements of +the Fibonacci sequence. + +@example +@group +fib = ones (1, 10); +i = 3; +while (i <= 10) + fib (i) = fib (i-1) + fib (i-2); + i++; +endwhile +@end group +@end example + +@noindent +Here the body of the loop contains two statements. + +The loop works like this: first, the value of @code{i} is set to 3. +Then, the @code{while} tests whether @code{i} is less than or equal to +10. This is the case when @code{i} equals 3, so the value of the +@code{i}-th element of @code{fib} is set to the sum of the previous two +values in the sequence. Then the @code{i++} increments the value of +@code{i} and the loop repeats. The loop terminates when @code{i} +reaches 11. + +A newline is not required between the condition and the +body; but using one makes the program clearer unless the body is very +simple. + +@node The for Statement, The break Statement, The while Statement, Statements +@section The @code{for} Statement +@cindex @code{for} statement +@cindex @code{endfor} statement + +The @code{for} statement makes it more convenient to count iterations of a +loop. The general form of the @code{for} statement looks like this: + +@example +@group +for @var{var} = @var{expression} + @var{body} +endfor +@end group +@end example + +@noindent +The assignment expression in the @code{for} statement works a bit +differently than Octave's normal assignment statement. Instead of +assigning the complete result of the expression, it assigns each column +of the expression to @var{var} in turn. If @var{expression} is either +a row vector or a scalar, the value of @var{var} will be a scalar each +time the loop body is executed. If @var{var} is a column vector or a +matrix, @var{var} will be a column vector each time the loop body is +executed. + +The following example shows another way to create a vector containing +the first ten elements of the Fibonacci sequence, this time using the +@code{for} statement: + +@example +@group +fib = ones (1, 10); +for i = 3:10 + fib (i) = fib (i-1) + fib (i-2); +endfor +@end group +@end example + +@noindent +This code works by first evaluating the expression @samp{3:10}, to +produce a range of values from 3 to 10 inclusive. Then the variable +@code{i} is assigned the first element of the range and the body of the +loop is executed once. When the end of the loop body is reached, the +next value in the range is assigned to the variable @code{i}, and the +loop body is executed again. This process continues until there are no +more elements to assign. + +In the @code{for} statement, @var{body} stands for any statement or list +of statements. + +Although it is possible to rewrite all @code{for} loops as @code{while} +loops, the Octave language has both statements because often a +@code{for} loop is both less work to type and more natural to think of. +Counting the number of iterations is very common in loops and it can be +easier to think of this counting as part of looping rather than as +something to do inside the loop. + +@node The break Statement, The continue Statement, The for Statement, Statements +@section The @code{break} Statement +@cindex @code{break} statement + +The @code{break} statement jumps out of the innermost @code{for} or +@code{while} loop that encloses it. The @code{break} statement may only +be used within the body of a loop. The following example finds the +smallest divisor of a given integer, and also identifies prime numbers: + +@example +@group +num = 103; +div = 2; +while (div*div <= num) + if (rem (num, div) == 0) + break; + endif + div++; +endwhile +if (rem (num, div) == 0) + printf ("Smallest divisor of %d is %d\n", num, div) +else + printf ("%d is prime\n", num); +endif +@end group +@end example + +When the remainder is zero in the first @code{while} statement, Octave +immediately @dfn{breaks out} of the loop. This means that Octave +proceeds immediately to the statement following the loop and continues +processing. (This is very different from the @code{exit} statement +which stops the entire Octave program.) + +Here is another program equivalent to the previous one. It illustrates +how the @var{condition} of a @code{while} statement could just as well +be replaced with a @code{break} inside an @code{if}: + +@example +@group +@group +num = 103; +div = 2; +while (1) + if (rem (num, div) == 0) + printf ("Smallest divisor of %d is %d\n", num, div); + break; + endif + div++; + if (div*div > num) + printf ("%d is prime\n", num); + break; + endif +endwhile +@end group +@end group +@end example + +@node The continue Statement, The unwind_protect Statement, The break Statement, Statements +@section The @code{continue} Statement +@cindex @code{continue} statement + +The @code{continue} statement, like @code{break}, is used only inside +@code{for} or @code{while} loops. It skips over the rest of the loop +body, causing the next cycle around the loop to begin immediately. +Contrast this with @code{break}, which jumps out of the loop altogether. +Here is an example: + +@example +@group +# print elements of a vector of random +# integers that are even. + +# first, create a row vector of 10 random +# integers with values between 0 and 100: + +vec = round (rand (1, 10) * 100); + +# print what we're interested in: + +for x = vec + if (rem (x, 2) != 0) + continue; + endif + printf ("%d\n", x); +endfor +@end group +@end example + +If one of the elements of @var{vec} is an odd number, this example skips +the print statement for that element, and continues back to the first +statement in the loop. + +This is not a practical example of the @code{continue} statement, but it +should give you a clear understanding of how it works. Normally, one +would probably write the loop like this: + +@example +@group +for x = vec + if (rem (x, 2) == 0) + printf ("%d\n", x); + endif +endfor +@end group +@end example + +@node The unwind_protect Statement, The try Statement, The continue Statement, Statements +@section The @code{unwind_protect} Statement +@cindex @code{unwind_protect} statement +@cindex @code{unwind_protect_cleanup} +@cindex @code{end_unwind_protect} + +Octave supports a limited form of exception handling modelled after the +unwind-protect form of Lisp. + +The general form of an @code{unwind_protect} block looks like this: + +@example +@group +unwind_protect + @var{body} +unwind_protect_cleanup + @var{cleanup} +end_unwind_protect +@end group +@end example + +@noindent +Where @var{body} and @var{cleanup} are both optional and may contain any +Octave expressions or commands. The statements in @var{cleanup} are +guaranteed to be executed regardless of how control exits @var{body}. + +This is useful to protect temporary changes to global variables from +possible errors. For example, the following code will always restore +the original value of the built-in variable @code{do_fortran_indexing} +even if an error occurs while performing the indexing operation. + +@example +save_do_fortran_indexing = do_fortran_indexing; +unwind_protect + do_fortran_indexing = "true"; + elt = a (idx) +unwind_protect_cleanup + do_fortran_indexing = save_do_fortran_indexing; +end_unwind_protect +@end example + +Without @code{unwind_protect}, the value of @var{do_fortran_indexing} +would not be restored if an error occurs while performing the indexing +operation because evaluation would stop at the point of the error and +the statement to restore the value would not be executed. + +@node The try Statement, Continuation Lines, The unwind_protect Statement, Statements +@section The @code{try} Statement +@cindex @code{try} statement +@cindex @code{catch} +@cindex @code{end_try_catch} + +In addition to unwind_protect, Octave supports another limited form of +exception handling. + +The general form of a @code{try} block looks like this: + +@example +@group +try + @var{body} +catch + @var{cleanup} +end_try_catch +@end group +@end example + +Where @var{body} and @var{cleanup} are both optional and may contain any +Octave expressions or commands. The statements in @var{cleanup} are +only executed if an error occurs in @var{body}. + +No warnings or error messages are printed while @var{body} is +executing. If an error does occur during the execution of @var{body}, +@var{cleanup} can access the text of the message that would have been +printed in the builtin constant @code{__error_text__}. This is the same +as @code{eval (@var{try}, @var{catch})} (which may now also use +@code{__error_text__}) but it is more efficient since the commands do +not need to be parsed each time the @var{try} and @var{catch} statements +are evaluated. + +Octave's @var{try} block is a very limited variation on the Lisp +condition-case form (limited because it cannot handle different classes +of errors separately). Perhaps at some point Octave can have some sort +of classification of errors and try-catch can be improved to be as +powerful as condition-case in Lisp. + +@cindex continuation lines +@cindex @code{...} continuation marker +@cindex @code{\} continuation marker + +@node Continuation Lines, , The try Statement, Statements +@section Continuation Lines + +In the Octave language, most statements end with a newline character and +you must tell Octave to ignore the newline character in order to +continue a statement from one line to the next. Lines that end with the +characters @code{...} or @code{\} are joined with the following line +before they are divided into tokens by Octave's parser. For example, +the lines + +@example +x = long_variable_name ... + + longer_variable_name \ + - 42 +@end example + +@noindent +form a single statement. The backslash character on the second line +above is interpreted a continuation character, @emph{not} as a division +operator. + +For continuation lines that do not occur inside string constants, +whitespace and comments may appear between the continuation marker and +the newline character. For example, the statement + +@example +x = long_variable_name ... % comment one + + longer_variable_name \ % comment two + - 42 % last comment +@end example + +@noindent +is equivalent to the one shown above. + +In some cases, Octave will allow you to continue lines without having to +specify continuation characters. For example, it is possible to write +statements like + +@example +if (big_long_variable_name == other_long_variable_name + || not_so_short_variable_name > 4 + && y > x) + some (code, here); +endif +@end example + +@noindent +without having to clutter up the if statement with continuation +characters.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/strings.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,271 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@cindex strings + +@node String Functions, System Utilities, Matrix Manipulation, Top +@chapter String Functions + +Octave currently has a limited ability to work with strings. + +@findex strcmp + +The function @code{strcmp (@var{s1}, @var{s2})} compares two strings, +returning 1 if they are the same, and 0 otherwise. + +@strong{Note: For compatibility with @sc{Matlab}, Octave's strcmp +function returns 1 if the strings are equal, and 0 otherwise. This is +just the opposite of the corresponding C library function.} + +@findex int2str +@findex num2str + +The functions @code{int2str} and @code{num2str} convert a numeric +argument to a string. These functions are not very flexible, but are +provided for compatibility with @sc{Matlab}. For better control over +the results, use @code{sprintf} (@pxref{Formatted Output}). + +@findex setstr + +The function @code{setstr} can be used to convert a vector to a string. +Each element of the vector is converted to the corresponding ASCII +character. For example, + +@example +setstr ([97, 98, 99]) +@end example + +@noindent +creates the string + +@example +abc +@end example + +@findex undo_string_escapes + +The function @code{undo_string_escapes (@var{string})} converts special +characters in strings back to their escaped forms. For example, the +expression + +@example +bell = "\a"; +@end example + +@noindent +assigns the value of the alert character (control-g, ASCII code 7) to +the string variable @var{bell}. If this string is printed, the +system will ring the terminal bell (if it is possible). This is +normally the desired outcome. However, sometimes it is useful to be +able to print the original representation of the string, with the +special characters replaced by their escape sequences. For example, + +@example +octave:13> undo_string_escapes (bell) +ans = \a +@end example + +@noindent +replaces the unprintable alert character with its printable +representation. @xref{String Constants}, for a description of string +escapes. + +Here is a list of some other string functions. + +@ftable @code +@item bin2dec +Given a binary number @var{x} represented as a 0/1-string, +@code{bin2dec (@var{x})} returns the decimal number represented by +@var{x}. +@example +bin2dec ("1110") + @result{} 14 +@end example + +@item blanks +@code{blanks (@var{n})} returns a string of @var{n} blanks. + +@item deblank +@code{deblank (@var{s})} removes the trailing blanks from the string +@var{s}. + +@item dec2bin +If @var{x} is a nonnegative integer, @kbd{bin2dec (@var{x})} returns the +binary number corresponding to @var{x}. + +For example, +@example +dec2bin (14) + @result{} "1110" +@end example + +@item dec2hex +If @var{x} is a nonnegative integer, @kbd{dec2hex (@var{x})} returns the +hex number corresponding to @var{x}. + +For example, +@example +dec2hex (2748) + @result{} "abc" +@end example + +@item findstr +@kbd{findstr (@var{s}, @var{t} [,@var{overlap}])} returns the vector of +all positions in the longer of the two strings @var{s} and @var{t} where +an occurence of the shorter of the two starts. + +If the optional argument @var{overlap} is nonzero, the returned vector +can include overlapping positions (this is the default). + +For example, +@example +findstr ("ababab", "a") + @result{} [1 3 5] +findstr ("abababa", "aba", 0) + @result{} [1, 5] +@end example + +@item hex2dec +For a hex number @var{x} represented as a hex string, @kbd{hex2dec +(@var{x})} returns the decimal number corresponding to @var{x}. + +For example, +@example +hex2dec ("12B") + @result{} 299 +hex2dec ("12b") + @result{} 299 +@end example + +@item index +@kbd{index (@var{s}, @var{t})} returns the position of the first +occurence of the string @var{t} in the string @var{s}, or 0 if no +occurence is found. + +For example, +@example +index ("Teststring", "t") + @result{} 4 +@end example + +@strong{Note:} This function does not work for arrays of strings. + +@item rindex +@kbd{rindex (@var{s}, @var{t})} returns the position of the last +occurence of the string @var{t} in the string @var{s}, or 0 if no +occurence is found. + +For example, +@example +rindex ("Teststring", "t") + @result{} 6 +@end example + +@strong{Note:} This function does not work for arrays of strings. + +@item split +@kbd{@var{m} = split (@var{s}, @var{t})} divides the string @var{s} into +pieces separated by @var{t}, and stores the pieces as the rows of @var{m} +(padded with blanks to form a valid matrix). + +For example, +@example +split ("Test string", "t") + @result{} Tes + s + ring +@end example + +@item str2mat +@kbd{str2mat (@var{s_1}, @dots{}, @var{s_n})} returns a matrix +containing the strings @var{s_1}, @dots{}, @var{s_n} as its rows. +Each string is padded with blanks in order to form a valid matrix. + +@quotation +@strong{Note:} +This function is modelled after @sc{MATLAB}. In Octave, you can create +a matrix of strings by @kbd{[@var{s_1}; @dots{}; @var{s_n}]}. +@end quotation + +@item strrep +@kbd{strrep (@var{s}, @var{x}, @var{y})} replaces all occurences of the +substring @var{x} of the string @var{s} with the string @var{y}. + +For example, +@example +strrep ("This is a test string", "is", "&%$") + @result{} Th&%$ &%$ a test string +@end example + +@item substr +@kbd{substr (@var{s}, @var{beg}, @var{len})} returns the substring of +@var{s} which starts at character number @var{beg} and is @var{len} +characters long. + +@quotation +@strong{Note:} +This function is patterned after AWK. You can get the same result by +@kbd{@var{s} (@var{beg} : (@var{beg} + @var{len} - 1))}. +@end quotation + +For example, +@example +substr ("This is a test string", 6, 9) + @result{} is a test +@end example + +@item tolower +@kbd{tolower (@var{s})} returns a copy of the string @var{s}, with each +upper-case character replaced by the corresponding lower-case one; +nonalphabetic characters are left unchanged. + +For example, +@example +tolower ("MiXeD cAsE 123") + @result{} "mixed case 123" +@end example + +@item toupper +@kbd{toupper (@var{s})} returns a copy of the string @var{s}, with each +lower-case character replaced by the corresponding upper-case one; +nonalphabetic characters are left unchanged. + +For example, +@example +toupper ("MiXeD cAsE 123") + @result{} "MIXED CASE 123" +@end example +@end ftable + +Octave also provides the following C-type character class test +functions. They all operate on string arrays and return matrices of +zeros and ones. Elements that are nonzero indicate that the condition +was true for the corresponding character in the string array. + +@ftable @code +@item isalnum +letter or a digit +@item isalpha +letter +@item isascii +ascii +@item iscntrl +control character +@item isdigit +digit +@item isgraph +printable (but not space character) +@item islower +lower case +@item isprint +printable (including space character) +@item ispunct +punctuation +@item isspace +whitespace +@item isupper +upper case +@item isxdigit +hexadecimal digit +@end ftable
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/system.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,577 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node System Utilities, Command History Functions, String Functions, Top +@chapter System Utilities + +This chapter describes the functions that are available to allow you to +get information about what is happening outside of Octave, while it is +still running, and use this information in your program. For example, +you can get information about environment variables, the current time, +and even start other programs from the Octave prompt. + +@menu +* Timing Utilities:: +* Filesystem Utilities:: +* Interacting with the OS:: +* System Information:: +* Other Functions:: +@end menu + +@node Timing Utilities, Filesystem Utilities, System Utilities, System Utilities +@section Timing Utilities + +@findex time + +The function @code{time} returns the current time as the number of +seconds since the epoch. The epoch is referenced to 00:00:00 CUT +(Coordinated Universal Time) 1 Jan 1970. + +Several of Octave's time functions a data structure for time that +includes the following elements: + +@table @code +@item usec +Microseconds after the second (0-999999). + +@item sec +Seconds after the minute (0-61). This number can be 61 to account +for leap seconds. + +@item min +Minutes after the hour (0-59). + +@item hour +Hours since midnight (0-23). + +@item mday +Day of the month (1-31). + +@item mon +Months since January (0-11). + +@item year +Years since 1900. + +@item wday +Days since Sunday (0-6). + +@item yday +Days since January 1 (0-365). + +@item isdst +Daylight Savings Time flag. + +@item zone +Time zone. +@end table + +@findex localtime +@findex gmtime + +Given a value returned from time (or any nonnegative integer) the +function @code{localtime} returns a time structure corresponding to the +local time zone, and @code{gmtime} returns a time structure +corresponding to CUT. + +@findex asctime +@findex ctime + +The function @code{asctime} formats a time structure the following +five-field format: Thu Mar 28 08:40:14 1996. The function +@code{ctime (time)} is equivalent to @code{asctime (localtime (time))}. + +@findex strftime + +The function @code{strftime} can be used to format a time structure in a +very flexible way using @samp{%} substitutions similar to those in printf. +Except where noted, substituted fields have a fixed size; numeric fields +are padded if necessary. Padding is with zeros by default; for fields +that display a single number, padding can be changed or inhibited by +following the @samp{%} with one of the modifiers described below. Unknown +field specifiers are copied as normal characters. All other characters +are copied to the output without change. + +Octave's @code{strftime} function supports a superset of the ANSI C +field specifiers. + +@noindent +Literal character fields: + +@table @code +@item % +% character. + +@item n +Newline character. + +@item t +Tab character. +@end table + +@noindent +Numeric modifiers (a nonstandard extension): + +@table @code +@item - +Do not pad the field. + +@item _ +Pad the field with spaces. +@end table + +@noindent +Time fields: + +@table @code +@item %H +Hour (00-23). + +@item %I +Hour (01-12). + +@item %k +Hour (0-23). + +@item %l +Hour (1-12). + +@item %M +Minute (00-59). + +@item %p +Locale's AM or PM. + +@item %r +Time, 12-hour (hh:mm:ss [AP]M). + +@item %R +Time, 24-hour (hh:mm). + +@item %s +Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension). + +@item %S +Second (00-61). + +@item %T +Time, 24-hour (hh:mm:ss). + +@item %X +Locale's time representation (%H:%M:%S). + +@item %Z +Time zone (EDT), or nothing if no time zone is determinable. +@end table + +@noindent +Date fields: + +@table @code +@item %a +Locale's abbreviated weekday name (Sun-Sat). + +@item %A +Locale's full weekday name, variable length (Sunday-Saturday). + +@item %b +Locale's abbreviated month name (Jan-Dec). + +@item %B +Locale's full month name, variable length (January-December). + +@item %c +Locale's date and time (Sat Nov 04 12:02:33 EST 1989). + +@item %C +Century (00-99). + +@item %d +Day of month (01-31). + +@item %e +Day of month ( 1-31). + +@item %D +Date (mm/dd/yy). + +@item %h +Same as %b. + +@item %j +Day of year (001-366). + +@item %m +Month (01-12). + +@item %U +Week number of year with Sunday as first day of week (00-53). + +@item %w +Day of week (0-6). + +@item %W +Week number of year with Monday as first day of week (00-53). + +@item %x +Locale's date representation (mm/dd/yy). + +@item %y +Last two digits of year (00-99). + +@item %Y +Year (1970-). +@end table + +@findex clock + +The function @code{clock} returns a vector containing the current year, +month (1-12), day (1-31), hour (0-23), minute (0-59) and second (0-61). +For example, + +@example +octave:13> clock +ans = + + 1993 8 20 4 56 1 +@end example + +The function clock is more accurate on systems that have the +@code{gettimeofday} function. + +@findex date + +To get the date as a character string in the form DD-MMM-YY, use +the command @code{date}. For example, + +@example +octave:13> date +ans = 20-Aug-93 +@end example + +@findex tic +@findex toc +@findex etime + +Octave also has functions for computing time intervals and CPU time +used. The functions @code{tic} and @code{toc} can be used to set and +check a wall-clock timer. For example, + +@example +tic (); +# many computations later... +elapsed_time = toc (); +@end example + +@noindent +will set the variable @code{elapsed_time} to the number of seconds since +the most recent call to the function @code{tic}. + +The function @code{etime} provides another way to get elapsed wall-clock +time by returning the difference (in seconds) between two time values +returned from @code{clock}. For example: + +@example +t0 = clock (); +# many computations later... +elapsed_time = etime (clock (), t0); +@end example + +@noindent +will set the variable @code{elapsed_time} to the number of seconds since +the variable @code{t0} was set. + +@findex cputime + +The function @code{cputime} allows you to obtain information about the +amount of CPU time your Octave session is using. For example, + +@example +[total, user, system] = cputime (); +@end example + +@noindent +returns the CPU time used by your Octave session. The first output is +the total time spent executing your process and is equal to the sum of +second and third outputs, which are the number of CPU seconds spent +executing in user mode and the number of CPU seconds spent executing in +system mode, respectively. If your system does not have a way to report +CPU time usage, @code{cputime} returns 0 for each of its output values. + +@findex is_leap_year + +Finally, Octave's function @code{is_leap_year} returns 1 if the given +year is a leap year and 0 otherwise. If no arguments are provided, +@code{is_leap_year} will use the current year. For example, + +@example +octave:13> is_leap_year (2000) +ans = 1 +@end example + +@noindent +Contrary to what many people who post misinformation to Usenet +apparently believe, Octave knows that the year 2000 will be a leap year. + +@node Filesystem Utilities, Interacting with the OS, Timing Utilities, System Utilities +@section Filesystem Utilities + +Octave includes the following functions for renaming and deleting files, +creating, deleting, and reading directories, and for getting information +about the status of files. + +@ftable @code +@item rename (@var{from}, @var{to}) +Rename a file. + +@item unlink (@var{file}) +Delete a file. + +@item readdir (@var{dir}) +Returns names of files in the directory @var{dir} as an array of +strings. + +@item mkdir (@var{dir}) +Create a directory + +@item rmdir (@var{dir}) +Remove a directory. + +@item umask (@var{mask}) +Set permission mask for file creation. +@c XXX FIXME XXX -- this needs to be explained, but I don't feel up to +@c it just now... + +@item stat (@var{file}) +Get information about a file. If @var{file} is a symbolic link, +@code{stat} returns information about the file that the symbolic link +references. + +@item lstat (@var{file}) +Get information about a symbolic link. If @var{file} is not a symbolic +link, @code{lstat} is equivalent to @code{stat}. +@end ftable + +@node Interacting with the OS, System Information, Filesystem Utilities, System Utilities +@section Interacting with the OS + +@findex shell_cmd +@findex system + +You can execute any shell command using the function +@code{system (@var{cmd}, @var{flag})}. The second argument is optional. +If it is present, the output of the command is returned by +@code{system} as a string. If it is not supplied, any output from +the command is printed, with the standard output filtered through the +pager. For example, + +@c XXX FIXME XXX -- perhaps there should be another possible value for +@c the second argument, to indicate that the command is to be run +@c interactively, with the standard input and output connected to +@c /dev/tty. + +@example +users = system ("finger", 1) +@end example + +@noindent +places the output of the command @code{finger} in the variable +@code{users}. + +If you want to execute a shell command and have it behave as if it were +typed directly from the shell prompt, you may need to specify extra +arguments for the command. For example, to get @code{bash} to behave as +an interactive shell, you can type + +@example +system ("bash -i >/dev/tty"); +@end example + +The first argument, @samp{-i}, tells @code{bash} to behave as an +interactive shell, and the redirection of the standard output stream +prevents any output produced by @code{bash} from being sent back to +Octave, where it would be buffered until Octave displays another prompt. + +The @code{system} function can return two values. The first is any +output from the command that was written to the standard output stream, +and the second is the output status of the command. For example, + +@example +[output, status] = system ("echo foo; exit 2"); +@end example + +@noindent +will set the variable @code{output} to the string @samp{foo}, and the +variable @code{status} to the integer @samp{2}. + +The name @code{shell_cmd} exists for compatibility with earlier versions +of Octave. + +@findex getenv + +You can find the values of environment variables using the function +@code{getenv}. For example, + +@example +getenv ("PATH") +@end example + +@noindent +returns a string containing the value of your path. + +@findex putenv + +The function @code{putenv (@var{var}, @var{value})} sets the value of +the environment variable @var{var} to @var{value}. + +@findex clc +@findex home + +The functions @code{clc}, and @code{home} clear your +terminal screen and move the cursor to the upper left corner. + +@findex cd + +You can change the current working directory using the @code{cd} +command. Tilde expansion is performed on the path. For example, + +@example +cd ~/octave +@end example + +@noindent +Changes the current working directory to @file{~/octave}. If the +directory does not exist, an error message is printed and the working +directory is not changed. + +@findex chdir + +The name @code{chdir} is an alias for @code{cd}. + +@findex pwd + +The command @code{pwd} prints the current working directory. + +@findex dir +@findex ls + +The functions @code{dir} and @code{ls} list directory contents. For +example, + +@example +octave:13> ls -l +total 12 +-rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m +-rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m +@end example + +The @code{dir} and @code{ls} commands are implemented by calling your +system's directory listing command, so the available options may vary +from system to system. + +@node System Information, Other Functions, Interacting with the OS, System Utilities +@section System Information + +@findex computer + +If possible, @code{computer} prints a string of the form +@var{cpu}-@var{vendor}-@var{os} that identifies the kind of computer +Octave is running on. For example, + +@example +octave:13> computer +sparc-sun-sunos4.1.2 +@end example + +@findex isieee + +The function @code{isieee} returns 1 if your computer claims to conform +to the IEEE standard for floating point calculations. + +@findex version +The function @code{version} returns Octave's version number as a string. +This is also the value of the built-in variable @code{OCTAVE_VERSION}. +@xref{Built-in Variables}. + +@findex getrusage + +The function @code{getrusage} returns a structure containing a number of +statistics about the current Octave process. Not all fields are +available on all systems. If it is not possible to get CPU time +statistics, the CPU time slots are set to zero. Other missing data are +replaced by NaN. Here is a list of all the possible fields that can be +present in the structure returned by @code{getrusage}: + +@table @code +@item +@item idrss +Unshared data size. + +@item inblock +Number of block input operations. + +@item isrss +Unshared stack size. + +@item ixrss +Shared memory size. + +@item majflt +Number of major page faults. + +@item maxrss +Maximum data size. + +@item minflt +Number of minor page faults. + +@item msgrcv +Number of messages received. + +@item msgsnd +Number of messages sent. + +@item nivcsw +Number of involuntary context switches. + +@item nsignals +Number of signals received. + +@item nswap +Number of swaps. + +@item nvcsw +Number of voluntary context switches. + +@item oublock +Number of block output operations. + +@item stime +A structure containing the system CPU time used. The structure has the +elements @code{sec} (seconds) @code{usec} (microseconds). + +@item utime +A structure containing the user CPU time used. The structure has the +elements @code{sec} (seconds) @code{usec} (microseconds). +@end table + +@node Other Functions, , System Information, System Utilities +@section Other Functions + +@findex tilde_expand + +The function @code{tilde_expand (@var{string})} performs tilde expansion +on @var{string}. + +@findex pause + +The function @code{pause} allows you to suspend the execution of a +program. If invoked without any arguments, Octave waits until you type +a character. With a numeric argument, it pauses for the given number of +seconds. For example, the following statement prints a message and then +waits 5 seconds before clearing the screen. + +@example +fprintf (stderr, "wait please...\n"), pause (5), clc +@end example
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/using.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,54 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@cindex manual, using this +@cindex using this manual +@cindex language, Octave +@cindex program, @code{octave} +@cindex Octave language +@cindex @code{octave} program + +@node Using this Manual, Introduction, Acknowledgements, Top +@chapter Using the Manual + +The term Octave refers to a particular program, and to the language you +use to tell this program what to do. When we need to be careful, we +call the program ``the @code{octave} interpreter'' and the language +``the Octave language.'' The purpose of this manual is to explain both +the Octave language and how to run the @code{octave} interpreter. + +The term @dfn{Octave program} refers to a program written by you in +the Octave programming language. + +@xref{Introduction, ,Introduction}, for the bare essentials you need to +know to start using @code{octave}. + +@c XXX FIXME XXX -- need example program +@c +@c A sample Octave program has been provided for you (@pxref{Sample Program}). + +@c XXX FIXME XXX -- should we also have a glossary? +@c +@c If you find terms that you aren't familiar with, try looking them +@c up in the glossary (@pxref{Glossary}).@refill + +@c XXX FIXME XXX -- how about a language summary too? +@c +@c The entire Octave language is summarized for quick reference in +@c @xref{Octave Summary}. Look there if you just need +to refresh your memory about a particular feature. + +Most of the time complete Octave programs are used as examples, but in +some of the more advanced sections, only the part of the Octave program +that illustrates the concept being described is shown. + +@c XXX FIXME XXX -- should also explain typesetting conventions. + +@ifinfo +If you are reading this in GNU Emacs using Info, you can copy the regions +of text showing these sample files into your own test files. This way you +can try out the examples shown in the remainder of this document. You do +this by using the command @kbd{M-x write-region} to copy text from the Info +file into a file for use with @code{octave}. +@end ifinfo
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/var.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,916 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Built-in Variables, Arithmetic, Functions and Scripts, Top +@chapter Built-in Variables +@cindex variables +@cindex built-in variables +@cindex variables, built-in + +Most Octave variables are available for you to use for your own +purposes; they never change except when your program assigns values to +them, and never affect anything except when your program examines them. + +A number of variables have special built-in meanings. Some of them, +like @code{pi} and @code{eps} provide useful predefined constant values. +Others, like @code{do_fortran_indexing} and @code{page_screen_output} +are examined automatically by Octave, so that you can to tell Octave how +to do certain things. There are also two special variables, @code{ans} +and @code{PWD}, that are set automatically and carry information from +the internal workings of Octave to your program. + +This chapter documents all the built-in variables of Octave. +Most of them are also documented in the chapters that describe functions +that use them, or are affected by their values. +@c XXX FIXME XXX -- this should eventually happen. + +@menu +* Predefined Constants:: +* User Preferences:: +* Other Built-in Variables:: +* Summary of Preference Variables:: +@end menu + +@node Predefined Constants, User Preferences, Built-in Variables, Built-in Variables +@section Predefined Constants + +@vtable @code +@item I@r{,} i@r{,} J@r{,} j +A pure imaginary number, defined as +@iftex +@tex + $\sqrt{-1}$. +@end tex +@end iftex +@ifinfo + @code{sqrt (-1)}. +@end ifinfo +The @code{I} and @code{J} forms are true constants, and cannot be +modified. The @code{i} and @code{j} forms are like ordinary variables, +and may be used for other purposes. However, unlike other variables, +they once again assume their special predefined values if they are +cleared @xref{Miscellaneous Utilities}. + +@item Inf@r{,} inf +Infinity. This is the result of an operation like 1/0, or an operation +that results in a floating point overflow. + +@item NaN@r{,} nan +Not a number. This is the result of an operation like @samp{0/0}, or +@samp{Inf - Inf}, or any operation with a NaN. + +@item SEEK_SET +@itemx SEEK_CUR +@itemx SEEK_END +These variables may be used as the optional third argument for the +function @code{fseek}. + +@item argv +The command line arguments passed to Octave are available in this +variable. For example, if you invoked Octave using the command + +@example +octave --no-line-editing --silent +@end example + +@noindent +@code{argv} would be a string vector with the elements +@code{--no-line-editing} and @code{--silent}. The following code will +print the command line arguments: + +@example +for i = 1:nargin + printf ("argv(%d) = %s\n", i, argv(i,:)); +endfor +@end example + +@noindent +@xref{Index Expressions} for an explanation of how to properly index +arrays of strings and substrings in Octave. + +@item eps +The machine precision. More precisely, @code{eps} is the largest +relative spacing between any two adjacent numbers in the machine's +floating point system. This number is obviously system-dependent. On +machines that support 64 bit IEEE floating point arithmetic, @code{eps} +is approximately +@ifinfo + 2.2204e-16. +@end ifinfo +@iftex +@tex + $2.2204\times10^{-16}$. +@end tex +@end iftex + +@item nargin +The value of @code{nargin} is automatically set to the number of command +line arguments. It is also used in the context of user-defined +functions to indicate the number of arguments that were passed to the +function. If you need to know the number of command line arguments +inside a function, you must define a global variable and save the +initial value of nargin in the global variable. + +@item pi +The ratio of the circumference of a circle to its diameter. +Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}. + +@item program_invocation_name +@itemx program_name +When Octave starts, the value of @code{program_invocation_name} is +automatically set to the name that was typed at the shell prompt to run +Octave, and the value of @code{program_name} is automatically set to the +final component of @code{program_invocation_name}. For example, if you +typed @file{/usr/local/bin/octave} to start Octave, +@code{program_invocation_name} would have the value +@file{/usr/local/bin/octave}, and @code{program_name} would have the +value @code{octave}. + +If executing a script from the command line (e.g., @code{octave foo.m} +or using an executable Octave script, the program name is set to the +name of the script. @xref{Executable Octave Programs} for an example of +how to create an executable Octave script. + +@ignore +@item read_only_constants +XXX FIXME XXX -- need description here. +@end ignore + +@item realmax +The largest floating point number that is representable. The actual +value is system-dependent. On machines that support 64 bit IEEE +floating point arithmetic, @code{realmax} is approximately +@ifinfo + 1.7977e+308 +@end ifinfo +@iftex +@tex + $1.7977\times10^{308}$. +@end tex +@end iftex + +@item realmin +The smallest floating point number that is representable. The actual +value is system-dependent. On machines that support 64 bit IEEE +floating point arithmetic, @code{realmin} is approximately +@ifinfo + 2.2251e-308 +@end ifinfo +@iftex +@tex + $2.2251\times10^{-308}$. +@end tex +@end iftex + +@item stdin +@itemx stdout +@itemx stderr +These variables are the file numbers corresponding to the standard +input, standard output, and standard error streams. These streams are +preconnected and available when Octave starts. +@end vtable + +@node User Preferences, Other Built-in Variables, Predefined Constants, Built-in Variables +@section User Preferences + +This section describes the variables that you can use to customize +Octave's behavior. + +Normally, preferences are set in the file @file{~/.octaverc}, so that +you can customize your environment in the same way each time you use +Octave without having to remember and retype all the necessary commands. +@xref{Startup Files} for more information. + +XXX FIXME XXX -- say something here to explain @code{"true"}, +@code{"false"}, etc. + +@vtable @code +@item EDITOR +A string naming the editor to use with the @code{edit_history} command. +If the environment variable @code{EDITOR} is set when Octave starts, its +value is used as the default. Otherwise, @code{EDITOR} is set to +@code{"vi"}. + +@item EXEC_PATH +The variable @code{EXEC_PATH} is a colon separated list of directories +to search when executing subprograms. Its initial value is taken from +the environment variable @code{OCTAVE_EXEC_PATH} (if it exists) or +@code{PATH}, but that value can be overridden by the the command line +argument @code{--exec-path PATH}, or by setting the value of +@code{EXEC_PATH} in a startup script. If the value of @code{EXEC_PATH} +begins (ends) with a colon, the directories +@code{OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH} and +@code{OCTAVE_HOME/bin} are prepended (appended) to @code{EXEC_PATH} (if +you don't specify a value for @code{EXEC_PATH} explicitly, these special +directories are prepended to your shell path). + +@item IMAGEPATH +A colon separated list of directories in which to search for image +files. @xref{Image Processing} for a description of Octave's image +processing capabilities. + +@item INFO_FILE +The variable @code{INFO_FILE} names the location of the Octave info file. +The default value is @code{"@value{OCTAVEHOME}/info/octave.info"}. + +@item INFO_PROGRAM +The variable @code{INFO_PROGRAM} names the info program to run. Its +initial value is +@code{@value{OCTAVEHOME}/libexec/octave/VERSION/exec/ARCH/info}, but +that value can be overridden by the environment variable +@code{OCTAVE_INFO_PROGRAM}, or the command line argument +@code{--info-program NAME}, or by setting the value of +@code{INFO_PROGRAM} in a startup script. + +@item LOADPATH +A colon separated list of directories in which to search for function +files. @xref{Functions and Scripts}. The value of @code{LOADPATH} +overrides the environment variable @code{OCTAVE_PATH}. @xref{Installation}. + +@code{LOADPATH} is now handled in the same way as @TeX{} handles +@code{TEXINPUTS}. If the path starts with @samp{:}, the standard path +is prepended to the value of @code{LOADPATH}. If it ends with @samp{:} +the standard path is appended to the value of @code{LOADPATH}. + +In addition, if any path element ends in @samp{//}, that directory and +all subdirectories it contains are searched recursively for function +files. This can result in a slight delay as Octave caches the lists of +files found in the @code{LOADPATH} the first time Octave searches for a +function. After that, searching is usually much faster because Octave +normally only needs to search its internal cache for files. + +To improve performance of recursive directory searching, it is best for +each directory that is to be searched recursively to contain +@emph{either} additional subdirectories @emph{or} function files, but +not a mixture of both. + +@xref{Organization of Functions} for a description of the function file +directories that are distributed with Octave. + +@item OCTAVE_VERSION +The version number of Octave, as a string. + +@item PAGER +The default value is @code{"less"}, or, if @code{less} is not available +on your system, @code{"more"}. @xref{Installation}, and +@ref{Input and Output}. + +@item PS1 +The primary prompt string. When executing interactively, Octave +displays the primary prompt @code{PS1} when it is ready to read a +command. Octave allows the prompt to be customized by inserting a +number of backslash-escaped special characters that are decoded as +follows: + +@table @samp +@item \t +The time. +@item \d +The date. +@item \n +Begins a new line by printing the equivalent of a carriage return +followed by a line feed. +@item \s +The name of the program (usually just @code{octave}). +@item \w +The current working directory. +@item \W +The basename of the current working directory. +@item \u +The username of the current user. +@item \h +The hostname. +@item \H +The hostname, up to the first `.'. +@item \# +The command number of this command, counting from when Octave starts. +@item \! +The history number of this command. This differs from @samp{\#} by the +number of commands in the history list when Octave starts. +@item \$ +If the effective UID is 0, a #, otherwise a $. +@item \nnn +The character whose character code in octal is @samp{nnn}. +@item \\ +A backslash. +@end table + +The default value of @code{PS1} is @code{"\s:\#> "}. To change it, use a +command like + +@example +octave:13> PS1 = "\\u@@\\H> " +@end example + +@noindent +which will result in the prompt @samp{boris@@kremvax> } for the user +@samp{boris} logged in on the host @samp{kremvax.kgb.su}. Note that two +backslashes are required to enter a backslash into a string. +@xref{String Constants}. + +@item PS2 +The secondary prompt string, which is printed when Octave is +expecting additional input to complete a command. For example, when +defining a function over several lines, Octave will print the value of +@code{PS1} at the beginning of each line after the first. Octave allows +@code{PS2} to be customized in the same way as @code{PS1}. The default +value of @code{PS2} is @code{"> "}. + +@item PS4 +If Octave is invoked with the @code{--echo-input} option, the value of +@code{PS4} is printed before each line of input that is echoed. Octave +allows @code{PS4} to be customized in the same way as @code{PS1}. The +default value of @code{PS4} is @code{"+ "}. @xref{Invoking Octave}, for +a description of @code{--echo-input}. + +@item automatic_replot +If this variable is @code{"true"}, Octave will automatically send a +@code{replot} command to @code{gnuplot} each time the plot changes. +Since this is fairly inefficient, the default value is @code{"false"}. + +@item beep_on_error +If the value of @code{beep_on_error} is @code{"true"}, Octave will try +to ring your terminal's bell before printing an error message. The +default value is @code{"false"}. + +@item completion_append_char +The value of @code{completion_append_char} is used as the character to +append to successful command-line completion attempts. The default +value is @code{" "} (a single space). + +@item default_return_value +The value given to otherwise unitialized return values if +@code{define_all_return_values} is @code{"true"}. The default value is +@code{[]}. + +@item default_save_format +Specify the default format used by the @code{save} command. Options are +@code{"ascii"}, @code{"binary"}, @code{"mat-binary"}, or +@code{"float-binary"}. The default value is @code{ascii}. + +@item define_all_return_values +If the value of @code{define_all_return_values} is @code{"true"}, Octave +will substitute the value specified by @code{default_return_value} for +any return values that remain undefined when a function returns. The +default value is @code{"false"}. + +@item do_fortran_indexing +If the value of @code{do_fortran_indexing} is @code{"true"}, Octave allows +you to select elements of a two-dimensional matrix using a single index +by treating the matrix as a single vector created from the columns of +the matrix. The default value is @code{"false"}. + +@item empty_list_elements_ok +This variable controls whether Octave ignores empty matrices in a matrix +list. + +For example, if the value of @code{empty_list_elements_ok} is +@code{"true"}, Octave will ignore the empty matrices in the expression + +@example +a = [1, [], 3, [], 5] +@end example + +@noindent +and the variable @samp{a} will be assigned the value @samp{[ 1 3 5 ]}. + +The default value is @code{"warn"}. + +@item gnuplot_binary +The name of the program invoked by the plot command. The default value +is @code{"gnuplot"}. @xref{Installation}. + +@item gnuplot_has_multiplot +If the value of this variable is nonzero, Octave assumes that your copy +of gnuplot has the multiplot support that is included in recent +3.6beta releases. It's initial value is determined by configure, but it +can be changed in your startup script or at the command line in case +configure got it wrong, or if you upgrade your gnuplot installation. + +@item history_file +This variable specifies the name of the file used to store command +history. The default value is @code{"~/.octave_hist"}, but may be +overridden by the environment variable @code{OCTAVE_HISTFILE}. + +@item history_size +This variable specifies how many entries to store in the history file. +The default value is @code{1024}, but may be overridden by the +environment variable @code{OCTAVE_HISTSIZE}. + +@item ignore_function_time_stamp +This variable can be used to prevent Octave from making the system call +@code{stat()} each time it looks up functions defined in function files. +If @code{ignore_function_time_stamp} to @code{"system"}, Octave will not +automatically recompile function files in subdirectories of +@code{@value{OCTAVEHOME}/lib/@value{VERSION}} if they have changed since +they were last compiled, but will recompile other function files in the +@code{LOADPATH} if they change. If set to @code{"all"}, Octave will not +recompile any function files unless their definitions are removed with +@code{clear}. For any other value of @code{ignore_function_time_stamp}, +Octave will always check to see if functions defined in function files +need to recompiled. The default value of +@code{ignore_function_time_stamp} is @code{"system"}. + +@item implicit_str_to_num_ok +If the value of @code{implicit_str_to_num_ok} is @code{"true"}, implicit +conversions of strings to their numeric ASCII equivalents are allowed. +Otherwise, an error message is printed and control is returned to the +top level. The default value is @code{"false"}. + +@item ok_to_lose_imaginary_part +If the value of @code{ok_to_lose_imaginary_part} is @code{"true"}, +implicit conversions of complex numbers to real numbers are allowed (for +example, by fsolve). If the value is @code{"warn"}, the conversion is allowed, +but a warning is printed. Otherwise, an error message is printed and +control is returned to the top level. The default value is @code{"warn"}. + +@item output_max_field_width +This variable specifies the maximum width of a numeric output field. +The default value is 10. + +It is possible to achieve a wide range of output styles by using +different values of @code{output_precision} and +@code{output_max_field_width}. Reasonable combinations can be set using +the @code{format} function. @xref{Basic Input and Output}. + +@item output_precision +This variable specifies the minimum number of significant figures to +display for numeric output. The default value is 5. + +It is possible to achieve a wide range of output styles by using +different values of @code{output_precision} and +@code{output_max_field_width}. Reasonable combinations can be set using +the @code{format} function. @xref{Basic Input and Output}. + +@item page_screen_output +If the value of @code{page_screen_output} is @code{"true"}, all output +intended for the screen that is longer than one page is sent through a +pager. This allows you to view one screenful at a time. Some pagers +(such as @code{less}---see @ref{Installation}) are also capable of moving +backward on the output. The default value is @code{"true"}. +@xref{Input and Output}. + +You can choose the program to use as the pager by setting the variable +@code{PAGER}. + +@item prefer_column_vectors +If @code{prefer_column_vectors} is @code{"true"}, operations like + +@example +for i = 1:10 + a (i) = i; +endfor +@end example + +@noindent +(for @samp{a} previously undefined) produce column vectors. Otherwise, row +vectors are preferred. The default value is @code{"false"}. + +If a variable is already defined to be a vector (a matrix with a single +row or column), the original orientation is respected, regardless of the +value of @code{prefer_column_vectors}. + +@item prefer_zero_one_indexing +If the value of @code{prefer_zero_one_indexing} is @code{"true"}, Octave +will perform zero-one style indexing when there is a conflict with the +normal indexing rules. @xref{Index Expressions}. For example, given a +matrix + +@example +a = [1, 2, 3, 4] +@end example + +@noindent +with @code{prefer_zero_one_indexing} is set to @code{"true"}, the +expression + +@example +a ([1, 1, 1, 1]) +@end example + +@noindent +results in the matrix @samp{[ 1 2 3 4 ]}. If the value of +@code{prefer_zero_one_indexing} set to @code{"false"}, the result would be +the matrix @samp{[ 1 1 1 1 ]}. + +In the first case, Octave is selecting each element corresponding to a +@samp{1} in the index vector. In the second, Octave is selecting the +first element multiple times. + +The default value for @code{prefer_zero_one_indexing} is @code{"false"}. + +@item print_answer_id_name +If the value of @code{print_answer_id_name} is @code{"true"}, variable +names are printed along with the result. Otherwise, only the result +values are printed. The default value is @code{"true"}. + +@item print_empty_dimensions +If the value of @code{print_empty_dimensions} is @code{"true"}, the +dimensions of empty matrices are printed along with the empty matrix +symbol, @samp{[]}. For example, the expression + +@example +zeros (3, 0) +@end example + +@noindent +will print + +@example +ans = + +[](3x0) +@end example + +@item propagate_empty_matrices +If the value of @code{propagate_empty_matrices} is @code{"true"}, +functions like @code{inverse} and @code{svd} will return an empty matrix +if they are given one as an argument. The default value is @code{"true"}. +@xref{Empty Matrices}. + +@item resize_on_range_error +If the value of @code{resize_on_range_error} is @code{"true"}, expressions +like + +@example +for i = 1:10 + a (i) = i; +endfor +@end example + +@noindent +(for @samp{a} previously undefined) result in the variable @samp{a} +being resized to be just large enough to hold the new value. Otherwise +uninitialized elements are set to zero. If the value of +@code{resize_on_range_error} is @code{"false"}, an error message is +printed and control is returned to the top level. The default value is +@code{"true"}. + +@item return_last_computed_value +If the value of @code{return_last_computed_value} is true, and a +function is defined without explicitly specifying a return value, the +function will return the value of the last expression. Otherwise, no +value will be returned. The default value is @code{"false"}. + +For example, the function + +@example +function f () + 2 + 2; +endfunction +@end example + +@noindent +will either return nothing, if @code{return_last_computed_value} is +@code{"false"}, or 4, if it is @code{"true"}. + +@item save_precision +This variable specifies the number of digits to keep when saving data +with the @code{save} command. The default value is 17. + +@item saving_history +If the value of @code{saving_history} is @code{"true"}, command entered +on the command line are saved in the file specified by the variable +@code{history_file}. + +@item silent_functions +If the value of @code{silent_functions} is @code{"true"}, internal output +from a function is suppressed. Otherwise, the results of expressions +within a function body that are not terminated with a semicolon will +have their values printed. The default value is @code{"false"}. + +For example, if the function + +@example +function f () + 2 + 2 +endfunction +@end example + +@noindent +is executed, Octave will either print @samp{ans = 4} or nothing +depending on the value of @code{silent_functions}. + +@item split_long_rows +For large matrices, Octave may not be able to display all the columns of +a given row on one line of your screen. This can result in missing +information or output that is nearly impossible to decipher, depending +on whether your terminal truncates or wraps long lines. + +If the value of @code{split_long_rows} is @code{"true"}, Octave will +display the matrix in a series of smaller pieces, each of which can fit +within the limits of your terminal width. Each set of rows is labeled +so that you can easily see which columns are currently being displayed. +For example: + +@smallexample +octave:13> rand (2, 9) +ans = + + Columns 1 through 7: + + 0.92205 0.72628 0.99841 0.62590 0.82422 0.77486 0.30258 + 0.15999 0.79484 0.75443 0.86995 0.91430 0.23980 0.64591 + + Columns 8 and 9: + + 0.08894 0.13266 + 0.28008 0.65575 +@end smallexample + +The default value of @code{split_long_rows} is @code{"true"}. + +@item struct_levels_to_print +This variable controls the depth of nested structures to print. The +default is 2. + +@item suppress_verbose_help_message +If the value of @code{suppress_verbose_help_message} is @code{"true"}, +Octave will not add additional help information to the end of the output +from the @code{help} command and usage messages for built-in commands. + +@item treat_neg_dim_as_zero +If the value of @code{treat_neg_dim_as_zero} is @code{"true"}, expressions +like + +@example +eye (-1) +@end example + +@noindent +produce an empty matrix (i.e., row and column dimensions are zero). +Otherwise, an error message is printed and control is returned to the +top level. The default value is @code{"false"}. + +@item warn_assign_as_truth_value +If the value of @code{warn_assign_as_truth_value} is @code{"true"}, a +warning is issued for statements like + +@example +if (s = t) + ... +@end example + +@noindent +since such statements are not common, and it is likely that the intent +was to write + +@example +if (s == t) + ... +@end example + +@noindent +instead. + +There are times when it is useful to write code that contains +assignments within the condition of a @code{while} or @code{if} +statement. For example, statements like + +@example +while (c = getc()) + ... +@end example + +@noindent +are common in C programming. + +It is possible to avoid all warnings about such statements by setting +@code{warn_assign_as_truth_value} to @code{"false"}, but that may also +let real errors like + +@example +if (x = 1) # intended to test (x == 1)! + ... +@end example + +@noindent +slip by. + +In such cases, it is possible suppress errors for specific statements by +writing them with an extra set of parentheses. For example, writing the +previous example as + +@example +while ((c = getc())) + ... +@end example + +@noindent +will prevent the warning from being printed for this statement, while +allowing Octave to warn about other assignments used in conditional +contexts. + +The default value of @code{warn_assign_as_truth_value} is @code{"true"}. + +@item warn_comma_in_global_decl +If the value of @code{warn_comma_in_global_decl} is @code{"true"}, a +warning is issued for statements like + +@example +global a = 1, b +@end example + +@noindent +which makes the variables @samp{a} and @samp{b} global and assigns the +value 1 to the variable @samp{a}, because in this context, the comma is +not interpreted as a statement separator. + +The default value of @code{warn_comma_in_global_decl} is @code{"true"}. + +@item warn_divide_by_zero +If the value of @code{warn_divide_by_zero} is @code{"true"}, a warning +is issued when Octave encounters a division by zero. If the value is +@code{"false"}, the warning is omitted. The default value is +@code{"true"}. + +@item warn_function_name_clash +If the value of @code{warn_function_name_clash} is @code{"true"}, a +warning is issued when Octave finds that the name of a function defined +in a function file differs from the name of the file. If the value is +@code{"false"}, the warning is omitted. The default value is +@code{"true"}. + +@item warn_missing_semicolon +If the value of this variable is nonzero, Octave will warn when +statements in function definitions don't end in semicolons. The default +value is 0. + +@item whitespace_in_literal_matrix +This variable allows some control over how Octave decides to convert +spaces to commas and semicolons in matrix expressions like +@samp{[m (1)]} or + +@example +[ 1, 2, + 3, 4 ] +@end example + +If the value of @code{whitespace_in_literal_matrix} is @code{"ignore"}, +Octave will never insert a comma or a semicolon in a literal matrix +list. For example, the expression @samp{[1 2]} will result in an error +instead of being treated the same as @samp{[1, 2]}, and the expression + +@example +[ 1, 2, + 3, 4 ] +@end example + +@noindent +will result in the vector [1 2 3 4] instead of a matrix. + +If the value of @code{whitespace_in_literal_matrix} is @code{"traditional"}, +Octave will convert spaces to a comma between identifiers and @samp{(}. For +example, given the matrix + +@example +m = [3 2] +@end example + +@noindent +the expression + +@example +[m (1)] +@end example + +@noindent +will be parsed as + +@example +[m, (1)] +@end example + +@noindent +and will result in + +@example +[3 2 1] +@end example + +@noindent +and the expression + +@example +[ 1, 2, + 3, 4 ] +@end example + +@noindent +will result in a matrix because the newline character is converted to a +semicolon (row separator) even though there is a comma at the end of the +first line (trailing commas or semicolons are ignored). This is +apparently how @sc{Matlab} behaves. + +Any other value for @code{whitespace_in_literal_matrix} results in behavior +that is the same as traditional, except that Octave does not +convert spaces to a comma between identifiers and @samp{(}. For +example, the expression + +@example +[m (1)] +@end example + +will produce @samp{3}. This is the way Octave has always behaved. +@end vtable + +@node Other Built-in Variables, Summary of Preference Variables, User Preferences, Built-in Variables +@section Other Built-in Variables + +In addition to predefined constants and preference variables, there are +two other special built-in variables whose values are automatically +updated. + +@vtable @code +@item ans +This variable holds the most recently computed result that was not +explicitly assigned to a variable. For example, after the expression + +@example +3^2 + 4^2 +@end example + +@noindent +is evaluated, the value of @code{ans} is @samp{25}. + +@item PWD +The current working directory. The value of @code{PWD} is updated each +time the current working directory is changed with the @samp{cd} +command. @xref{System Utilities}. +@end vtable + +@node Summary of Preference Variables, , Other Built-in Variables, Built-in Variables +@section Summary of Preference Variables + +Here is a summary of all of Octave's preference variables and their +default values. In the following table @code{OCT_HOME} stands for +the root directory where Octave is installed, @code{VERSION} stands +for the Octave version number, and @code{SYS} stands for the type of +system for which Octave was compiled (for example, +@code{alpha-dec-osf3.2}). + +@smallexample +EDITOR "vi" +EXEC_PATH ":$PATH" +INFO_FILE "OCT_HOME/info/octave.info" +INFO_PROGRAM "OCT_HOME/libexec/octave/VERSION/exec/SYS/info" +LOADPATH ".:OCT_HOME/lib/VERSION" +PAGER "less", or "more" +PS1 "\s:\#> " +PS2 "> " +PS4 "+ " +automatic_replot 0 +beep_on_error 0 +completion_append_char " " +default_return_value [] +do_fortran_indexing 0 +define_all_return_values 0 +empty_list_elements_ok "warn" +gnuplot_binary "gnuplot" +history_file "~/.octave_hist" +history_size 1024 +ignore_function_time_stamp "system" +implicit_str_to_num_ok 0 +ok_to_lose_imaginary_part "warn" +output_max_field_width 10 +output_precision 5 +page_screen_output 1 +prefer_column_vectors 0 +prefer_zero_one_indexing 0 +print_answer_id_name 1 +print_empty_dimensions 1 +@c read_only_constants 1 +resize_on_range_error 1 +return_last_computed_value 0 +save_precision 17 +saving_history 1 +silent_functions 0 +split_long_rows 1 +struct_levels_to_print 2 +suppress_verbose_help_message 1 +treat_neg_dim_as_zero 0 +warn_assign_as_truth_value 1 +warn_comma_in_global_decl 1 +warn_divide_by_zero 1 +warn_function_name_clash 1 +whitespace_in_literal_matrix "" +@end smallexample + +The following variables may be set from the environment or by a command +line option. + +@smallexample +Variable Environment Variable Option +-------- -------------------- ------ +EDITOR EDITOR +EXEC_PATH OCTAVE_EXEC_PATH --exec-path PATH +LOADPATH OCTAVE_PATH --path PATH +INFO_FILE OCTAVE_INFO_FILE --info-file FILE +INFO_PROGRAM OCTAVE_INFO_PROGRAM --info-program PROGRAM +history_size OCTAVE_HISTSIZE +history_file OCTAVE_HISTFILE +@end smallexample + +@c XXX FIXME XXX Might be nice to have a list of the settings required +@c to have Octave behave as much like @sc{Matlab} as is possible.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/interpreter/vr-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,8 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Variable Index, Function Index, Concept Index, Top +@unnumbered Variable Index + +@printindex vr
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/array.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,181 @@ +@node Arrays, Matrix and Vector @var{Operations}, Introduction, Top +@chapter Arrays +@cindex arrays + +@menu +* Constructors and Assignment:: +@end menu + +@node Constructors and Assignment, , Arrays, Arrays +@section Constructors and Assignment + +@deftypefn Constructor {} Array<T>::Array (void) +Create an array with no elements. +@end deftypefn + +@deftypefn Constructor {} Array<T>::Array (int @var{n} [, const T &@var{val}]) +Create an array with @var{n} elements. If the optional argument +@var{val} is supplied, the elements are initialized to @var{val}; +otherwise, they are left uninitialized. If @var{n} is less than zero, +the current error handler is invoked (@pxref{Error Handling}). +@end deftypefn + +@deftypefn Constructor {} Array<T>::Array (const Array<T> &@var{a}) +Create a copy of the @var{Array<T>} object @var{a}. Memory for the +@var{Array<T>} class is managed using a reference counting scheme, so +the cost of this operation is independent of the size of the array. +@end deftypefn + +@deftypefn Operator Array<T>& {Array<T>::operator =} (const Array<T> &@var{a}) +Assignment operator. Memory for the @var{Array<T>} class is managed +using a reference counting scheme, so the cost of this operation is +independent of the size of the array. +@end deftypefn + +@deftypefn Method int Array<T>::capacity (void) const +@deftypefnx Method int Array<T>::length (void) const +Return the length of the array. +@end deftypefn + +@deftypefn Method T& Array<T>::elem (int @var{n}) +@deftypefnx Method T& Array<T>::checkelem (int @var{n}) +@deftypefnx Method T& {Array<T>::operator ()} (int @var{n}) +If @var{n} is within the bounds of the array, return a reference to the +element indexed by @var{n}; otherwise, the current error handler is +invoked (@pxref{Error Handling}). +@end deftypefn + +@deftypefn Method T Array<T>::elem (int @var{n}) const +@deftypefnx Method T Array<T>::checkelem (int @var{n}) const +@deftypefnx Method T Array<T>::operator () (int @var{n}) const +If @var{n} is within the bounds of the array, return the value indexed +by @var{n}; otherwise, call the current error handler. +@xref{Error Handling}. +@end deftypefn + +@deftypefn Method T& Array<T>::xelem (int @var{n}) +@deftypefnx Method T Array<T>::xelem (int @var{n}) const +Return a reference to, or the value of, the element indexed by @var{n}. +These methods never perform bounds checking. +@end deftypefn + +@deftypefn Method void Array<T>::resize (int @var{n} [, const T &@var{val}]) +Change the size of the array to be @var{n} elements. All elements are +unchanged, except that if @var{n} is greater than the current size and +the optional argument @var{val} is provided, the additional elements are +initialized to @var{val}; otherwise, any additional elements are left +uninitialized. In the current implementation, if @var{n} is less than +the current size, the length is updated but no memory is released. +@end deftypefn + +@deftypefn Method {const T*} Array<T>::data (void) const +@end deftypefn + +@c Should this be public? +@c +@c T *fortran_vec (void) + +@deftypefn {} {} Array2 (void) +@deftypefnx {} {} Array2 (int @var{n}, int @var{m}) +@deftypefnx {} {} Array2 (int @var{n}, int @var{m}, const T &@var{val}) +@deftypefnx {} {} Array2 (const Array2<T> &@var{a}) +@deftypefnx {} {} Array2 (const DiagArray<T> &@var{a}) +@end deftypefn + +@deftypefn {} Array2<T>& {operator =} (const Array2<T> &@var{a}) +@end deftypefn + +@deftypefn {} int dim1 (void) const +@deftypefnx {} int rows (void) const +@end deftypefn + +@deftypefn {} int dim2 (void) const +@deftypefnx {} int cols (void) const +@deftypefnx {} int columns (void) const +@end deftypefn + +@deftypefn {} T& elem (int @var{i}, int @var{j}) +@deftypefnx {} T& checkelem (int @var{i}, int @var{j}) +@deftypefnx {} T& {operator ()} (int @var{i}, int @var{j}) +@end deftypefn + +@c This needs to be fixed. +@c +@c T& xelem (int i, int j) +@c +@c T elem (int i, int j) const +@c T checkelem (int i, int j) const +@c T operator () (int i, int j) const + +@deftypefn {} void resize (int @var{n}, int @var{m}) +@deftypefnx {} void resize (int @var{n}, int @var{m}, const T &@var{val}) +@end deftypefn + +@deftypefn {} Array3 (void) +@deftypefnx {} Array3 (int @var{n}, int @var{m}, int @var{k}) +@deftypefnx {} Array3 (int @var{n}, int @var{m}, int @var{k}, const T &@var{val}) +@deftypefnx {} Array3 (const Array3<T> &@var{a}) +@end deftypefn + +@deftypefn {} Array3<T>& {operator =} (const Array3<T> &@var{a}) +@end deftypefn + +@deftypefn {} int dim1 (void) const +@deftypefnx {} int dim2 (void) const +@deftypefnx {} int dim3 (void) const +@end deftypefn + +@deftypefn {} T& elem (int @var{i}, int @var{j}, int @var{k}) +@deftypefnx {} T& checkelem (int @var{i}, int @var{j}, int @var{k}) +@deftypefnx {} T& {operator ()} (int @var{i}, int @var{j}, int @var{k}) +@end deftypefn + +@c This needs to be fixed. +@c +@c T& xelem (int i, int j, int k) +@c +@c T elem (int i, int j, int k) const +@c T checkelem (int i, int j, int k) const +@c T operator () (int i, int j, int k) const + +@deftypefn {} void resize (int @var{n}, int @var{m}, int @var{k}) +@deftypefnx {} void resize (int @var{n}, int @var{m}, int @var{k}, const T &@var{val}) +@end deftypefn + +@deftypefn {} {}DiagArray (void) +@deftypefnx {} {}DiagArray (int @var{n}) +@deftypefnx {} {}DiagArray (int @var{n}, const T &@var{val}) +@deftypefnx {} {}DiagArray (int @var{r}, int @var{c}) +@deftypefnx {} {}DiagArray (int @var{r}, int @var{c}, const T &@var{val}) +@deftypefnx {} {}DiagArray (const Array<T> &@var{a}) +@deftypefnx {} {}DiagArray (const DiagArray<T> &@var{a}) +@end deftypefn + +@deftypefn {} DiagArray<T>& {operator =} (const DiagArray<T> &@var{a}) +@end deftypefn + +@deftypefn {} int dim1 (void) const +@deftypefnx {} int rows (void) const +@end deftypefn + +@deftypefn {} int dim2 (void) const +@deftypefnx {} int cols (void) const +@deftypefnx {} int columns (void) const +@end deftypefn + +@deftypefn {} T& elem (int @var{r}, int @var{c}) +@deftypefnx {} T& checkelem (int @var{r}, int @var{c}) +@deftypefnx {} T& {operator ()} (int @var{r}, int @var{c}) +@end deftypefn + +@c This needs to be fixed. +@c +@c T& xelem (int r, int c) +@c +@c T elem (int r, int c) const +@c T checkelem (int r, int c) const +@c T operator () (int r, int c) const + +@deftypefn {} void resize (int @var{n}, int @var{m}) +@deftypefnx {} void resize (int @var{n}, int @var{m}, const T &@var{val}) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/bugs.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,6 @@ +@node Bugs, Concept Index, Installation, Top +@chapter Bugs +@cindex bugs, known +@cindex installation trouble +@cindex known causes of trouble +@cindex troubleshooting
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/cp-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,4 @@ +@node Concept Index, Function Index, Bugs, Top +@unnumbered Concept Index + +@printindex cp
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/dae.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,24 @@ +@node Differential Algebraic Equations, Quadrature, Ordinary Differential Equations, Top +@chapter Differential Algebraic Equations +@cindex DAE + +@deftypefn {} {}DAE (void) +@deftypefnx {} {}DAE (int @var{n}) +@deftypefnx {} {}DAE (const ColumnVector &@var{x}, double @var{time}, DAEFunc &@var{f}) +@deftypefnx {} {}DAE (const ColumnVector &@var{x}, ColumnVector &@var{xdot}, double @var{time}, DAEFunc &@var{f}) +@end deftypefn + +@deftypefn {} ColumnVector deriv (void) +@end deftypefn + +@deftypefn {} {virtual void} initialize (const ColumnVector &@var{x}, double @var{t}) +@deftypefnx {} {virtual void} initialize (const ColumnVector &@var{x}, ColumnVector &@var{xdot}, double @var{t}) +@end deftypefn + +@deftypefn {} ColumnVector integrate (double @var{t}) +@end deftypefn + +@deftypefn {} Matrix integrate (const ColumnVector &@var{tout}, Matrix &@var{xdot_out}) +@deftypefnx {} Matrix integrate (const ColumnVector &@var{tout}, Matrix &@var{xdot_out}, const ColumnVector &@var{tcrit}) +@end deftypefn +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/diffeq.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,102 @@ +@node Ordinary Differential Equations, Installation, Quadrature, Top +@chapter Ordinary Differential Equations +@cindex ODE + +@deftypefn {} {}ODE_options (void) +@deftypefnx {} {}ODE_options (const ODE_options &@var{opt}) +@end deftypefn + +@deftypefn {} ODE_options& {operator =} (const ODE_options &@var{opt}) +@end deftypefn + +@deftypefn {} void init (void) +@end deftypefn + +@deftypefn {} void copy (const ODE_options &@var{opt}) +@end deftypefn + +@deftypefn {} void set_default_options (void) +@end deftypefn + +@deftypefn {} void set_absolute_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_initial_step_size (double @var{val}) +@end deftypefn + +@deftypefn {} void set_maximum_step_size (double @var{val}) +@end deftypefn + +@deftypefn {} void set_minimum_step_size (double @var{val}) +@end deftypefn + +@deftypefn {} void set_relative_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} double absolute_tolerance (void) +@deftypefnx {} double initial_step_size (void) +@deftypefnx {} double maximum_step_size (void) +@deftypefnx {} double minimum_step_size (void) +@deftypefnx {} double relative_tolerance (void) +@end deftypefn + +@deftypefn {} {}ODE (void) +@deftypefnx {} {}ODE (int @var{n}) +@deftypefnx {} {}ODE (const ColumnVector &@var{state}, double @var{time}, const ODEFunc &@var{f}) +@end deftypefn + +@deftypefn {} {virtual int} size (void) const +@end deftypefn + +@deftypefn {} {virtual ColumnVector} state (void) const +@end deftypefn + +@deftypefn {} {virtual double} time (void) const +@end deftypefn + +@deftypefn {} {virtual void} force_restart (void) +@end deftypefn + +@deftypefn {} {virtual void} initialize (const ColumnVector &@var{x}, double @var{t}) +@end deftypefn + +@deftypefn {} {virtual void} set_stop_time (double @var{t}) +@end deftypefn + +@deftypefn {} {virtual void} clear_stop_time (void) +@end deftypefn + +@deftypefn {} {virtual ColumnVector} integrate (double @var{t}) +@end deftypefn + +@deftypefn {} void integrate (int @var{nsteps}, double @var{tstep}, ostream &@var{s}) +@end deftypefn + +@deftypefn {} Matrix integrate (const ColumnVector &@var{tout}) +@deftypefnx {} Matrix integrate (const ColumnVector &@var{tout}, const ColumnVector &@var{tcrit}) +@end deftypefn + +@node Differential Algebraic Equations, , Ordinary Differential Equations +@chapter Differential Algebraic Equations +@cindex DAE + +@deftypefn {} {}DAE (void) +@deftypefnx {} {}DAE (int @var{n}) +@deftypefnx {} {}DAE (const ColumnVector &@var{x}, double @var{time}, DAEFunc &@var{f}) +@deftypefnx {} {}DAE (const ColumnVector &@var{x}, ColumnVector &@var{xdot}, double @var{time}, DAEFunc &@var{f}) +@end deftypefn + +@deftypefn {} ColumnVector deriv (void) +@end deftypefn + +@deftypefn {} {virtual void} initialize (const ColumnVector &@var{x}, double @var{t}) +@deftypefnx {} {virtual void} initialize (const ColumnVector &@var{x}, ColumnVector &@var{xdot}, double @var{t}) +@end deftypefn + +@deftypefn {} ColumnVector integrate (double @var{t}) +@end deftypefn + +@deftypefn {} Matrix integrate (const ColumnVector &@var{tout}, Matrix &@var{xdot_out}) +@deftypefnx {} Matrix integrate (const ColumnVector &@var{tout}, Matrix &@var{xdot_out}, const ColumnVector &@var{tcrit}) +@end deftypefn +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/error.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,3 @@ +@node Error Handling +@chapter Error Handling +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/factor.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,299 @@ +@node Matrix Factorizations, Ranges, Matrix and Vector @var{Operations}, Top +@chapter Matrix Factorizations +@cindex matrix factorizations +@cindex factorizations + +@deftypefn {} {}AEPBALANCE (void) +@deftypefnx {} {}AEPBALANCE (const Matrix &@var{a}, const char *@var{balance_job}) +@deftypefnx {} {}AEPBALANCE (const AEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} AEPBALANCE& {operator =} (const AEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} Matrix balanced_matrix (void) const +@deftypefnx {} Matrix balancing_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const AEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} ComplexAEPBALANCE (void) +@deftypefnx {} ComplexAEPBALANCE (const ComplexMatrix &@var{a}, const char *@var{balance_job}) +@deftypefnx {} ComplexAEPBALANCE (const ComplexAEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} ComplexAEPBALANCE& {operator =} (const ComplexAEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix balanced_matrix (void) const +@deftypefnx {} ComplexMatrix balancing_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexAEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} {}DET (void) +@deftypefnx {} {}DET (const DET &@var{a}) +@end deftypefn + +@deftypefn {} DET& {operator =} (const DET &@var{a}) +@end deftypefn + +@deftypefn {} int value_will_overflow (void) const +@deftypefnx {} int value_will_underflow (void) const +@end deftypefn + +@deftypefn {} double coefficient (void) const +@deftypefnx {} int exponent (void) const +@deftypefnx {} double value (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const DET &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexDET (void) +@deftypefnx {} {}ComplexDET (const ComplexDET &@var{a}) +@end deftypefn + +@deftypefn {} ComplexDET& {operator =} (const ComplexDET &@var{a}) +@end deftypefn + +@deftypefn {} int value_will_overflow (void) const +@deftypefnx {} int value_will_underflow (void) const +@end deftypefn + +@deftypefn {} Complex coefficient (void) const +@deftypefnx {} int exponent (void) const +@deftypefnx {} Complex value (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexDET &@var{a}) +@end deftypefn + +@deftypefn {} {}GEPBALANCE (void) +@deftypefnx {} {}GEPBALANCE (const Matrix &@var{a}, const Matrix &, const char *@var{balance_job}) +@deftypefnx {} {}GEPBALANCE (const GEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} GEPBALANCE& {operator =} (const GEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} Matrix balanced_a_matrix (void) const +@deftypefnx {} Matrix balanced_b_matrix (void) const +@deftypefnx {} Matrix left_balancing_matrix (void) const +@deftypefnx {} Matrix right_balancing_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const GEPBALANCE &@var{a}) +@end deftypefn + +@deftypefn {} {}CHOL (void) +@deftypefnx {} {}CHOL (const Matrix &@var{a}) +@deftypefnx {} {}CHOL (const Matrix &@var{a}, int &@var{info}) +@deftypefnx {} {}CHOL (const CHOL &@var{a}) +@end deftypefn + +@deftypefn {} CHOL& {operator =} (const CHOL &@var{a}) +@end deftypefn + +@deftypefn {} Matrix chol_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const CHOL &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexCHOL (void) +@deftypefnx {} {}ComplexCHOL (const ComplexMatrix &@var{a}) +@deftypefnx {} {}ComplexCHOL (const ComplexMatrix &@var{a}, int &@var{info}) +@deftypefnx {} {}ComplexCHOL (const ComplexCHOL &@var{a}) +@end deftypefn + +@deftypefn {} ComplexCHOL& {operator =} (const ComplexCHOL &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix chol_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexCHOL &@var{a}) +@end deftypefn + +@deftypefn {} {}HESS (void) +@deftypefnx {} {}HESS (const Matrix &@var{a}) +@deftypefnx {} {}HESS (const Matrix&a, int &@var{info}) +@deftypefnx {} {}HESS (const HESS &@var{a}) +@end deftypefn + +@deftypefn {} HESS& {operator =} (const HESS &@var{a}) +@end deftypefn + +@deftypefn {} Matrix hess_matrix (void) const +@deftypefnx {} Matrix unitary_hess_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const HESS &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexHESS (void) +@deftypefnx {} {}ComplexHESS (const ComplexMatrix &@var{a}) +@deftypefnx {} {}ComplexHESS (const ComplexMatrix &@var{a}, int &@var{info}) +@deftypefnx {} {}ComplexHESS (const ComplexHESS &@var{a}) +@end deftypefn + +@deftypefn {} ComplexHESS& {operator =} (const ComplexHESS &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix hess_matrix (void) const +@deftypefnx {} ComplexMatrix unitary_hess_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexHESS &@var{a}) +@end deftypefn + +@deftypefn {} {}SCHUR (void) +@deftypefnx {} {}SCHUR (const Matrix &@var{a}, const char *@var{ord}) +@deftypefnx {} {}SCHUR (const Matrix &@var{a}, const char *@var{ord}, int &@var{info}) +@deftypefnx {} {}SCHUR (const SCHUR &@var{a}, const char *@var{ord}) +@end deftypefn + +@deftypefn {} SCHUR& {operator =} (const SCHUR &@var{a}) +@end deftypefn + +@deftypefn {} Matrix schur_matrix (void) const +@deftypefnx {} Matrix unitary_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const SCHUR &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexSCHUR (void) +@deftypefnx {} {}ComplexSCHUR (const ComplexMatrix &@var{a}, const char *@var{ord}) +@deftypefnx {} {}ComplexSCHUR (const ComplexMatrix &@var{a}, const char *@var{ord}, int &@var{info}) +@deftypefnx {} {}ComplexSCHUR (const ComplexSCHUR &@var{a}, const char *@var{ord}) +@end deftypefn + +@deftypefn {} ComplexSCHUR& {operator =} (const ComplexSCHUR &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix schur_matrix (void) const +@deftypefnx {} ComplexMatrix unitary_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexSCHUR &@var{a}) +@end deftypefn + +@deftypefn {} {}SVD (void) +@deftypefnx {} {}SVD (const Matrix &@var{a}) +@deftypefnx {} {}SVD (const Matrix &@var{a}, int &@var{info}) +@deftypefnx {} {}SVD (const SVD &@var{a}) +@end deftypefn + +@deftypefn {} SVD& {operator =} (const SVD &@var{a}) +@end deftypefn + +@deftypefn {} DiagMatrix singular_values (void) const +@deftypefnx {} Matrix left_singular_matrix (void) const +@deftypefnx {} Matrix right_singular_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const SVD &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexSVD (void) +@deftypefnx {} {}ComplexSVD (const ComplexMatrix &@var{a}) +@deftypefnx {} {}ComplexSVD (const ComplexMatrix &@var{a}, int &@var{info}) +@deftypefnx {} {}ComplexSVD (const ComplexSVD &@var{a}) +@end deftypefn + +@deftypefn {} ComplexSVD& {operator =} (const ComplexSVD &@var{a}) +@end deftypefn + +@deftypefn {} DiagMatrix singular_values (void) const +@deftypefnx {} ComplexMatrix left_singular_matrix (void) const +@deftypefnx {} ComplexMatrix right_singular_matrix (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexSVD &@var{a}) +@end deftypefn + +@deftypefn {} {}EIG (void) +@deftypefnx {} {}EIG (const Matrix &@var{a}) +@deftypefnx {} {}EIG (const Matrix &@var{a}, int &@var{info}) +@deftypefnx {} {}EIG (const ComplexMatrix &@var{a}) +@deftypefnx {} {}EIG (const ComplexMatrix &@var{a}, int &@var{info}) +@deftypefnx {} {}EIG (const EIG &@var{a}) +@end deftypefn + +@deftypefn {} EIG& {operator =} (const EIG &@var{a}) +@end deftypefn + +@deftypefn {} ComplexColumnVector eigenvalues (void) const +@end deftypefn + +@deftypefn {} ComplexMatrix eigenvectors (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const EIG &@var{a}) +@end deftypefn + +@deftypefn {} {}LU (void) +@deftypefnx {} {}LU (const Matrix &@var{a}) +@deftypefnx {} {}LU (const LU &@var{a}) +@end deftypefn + +@deftypefn {} LU& {operator =} (const LU &@var{a}) +@end deftypefn + +@deftypefn {} Matrix L (void) const +@deftypefnx {} Matrix U (void) const +@deftypefnx {} Matrix P (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const LU &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexLU (void) +@deftypefnx {} {}ComplexLU (const ComplexMatrix &@var{a}) +@deftypefnx {} {}ComplexLU (const ComplexLU &@var{a}) +@end deftypefn + +@deftypefn {} ComplexLU& {operator =} (const ComplexLU &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix L (void) const +@deftypefnx {} ComplexMatrix U (void) const +@deftypefnx {} Matrix P (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexLU &@var{a}) +@end deftypefn + +@deftypefn {} {}QR (void) +@deftypefnx {} {}QR (const Matrix &@var{A}) +@deftypefnx {} {}QR (const QR &@var{a}) +@end deftypefn + +@deftypefn {} QR& {operator =} (const QR &@var{a}) +@end deftypefn + +@deftypefn {} Matrix Q (void) const +@deftypefnx {} Matrix R (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const QR &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexQR (void) +@deftypefnx {} {}ComplexQR (const ComplexMatrix &@var{A}) +@deftypefnx {} {}ComplexQR (const ComplexQR &@var{a}) +@end deftypefn + +@deftypefn {} ComplexQR& {operator =} (const ComplexQR &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix Q (void) const +@deftypefnx {} ComplexMatrix R (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexQR &@var{a}) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/fn-idx.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,4 @@ +@node Function Index, , Concept Index, Top +@unnumbered Function Index + +@printindex fn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/gpl.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,397 @@ +@c Copyright (C) 1996 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@cindex warranty +@cindex copyright +@node Copying, Introduction, Acknowledgements, Top +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@example +Yoyodyne, Inc., hereby disclaims all copyright interest in the program +`Gnomovision' (which makes passes at compilers) written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end example + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/install.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,3 @@ +@node Installation, Bugs, Ordinary Differential Equations, Top +@chapter Installation +@cindex installation
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/intro.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,6 @@ +@node Introduction, Arrays, Copying, Top +@chapter A Brief Introduction to Octave +@cindex introduction + +This manual documents how to run, install and port Octave's C++ classes, +and how to report bugs.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/liboctave.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,139 @@ +% Copyright (C) 1996 John W. Eaton +% This is part of the Octave manual. +% For copying conditions, see the file gpl.texi. + +\input texinfo @c -*-texinfo-*- +@setfilename liboctave.info + +@c @smallbook +@c @setchapternewpage odd +@c @cropmarks +@c @finalout + +@c Smaller amounts of whitespace for the 8.5 by 11 inch format. +@tex +\global\chapheadingskip = 15pt plus 4pt minus 2pt +\global\secheadingskip = 12pt plus 3pt minus 2pt +\global\subsecheadingskip = 9pt plus 2pt minus 2pt +\global\parskip 6pt plus 1pt +@end tex + +@iftex +@set DONTINCLUDEGPL +@end iftex + +@defindex op + +@c xt@include conf.texi + +@settitle Octave C++ Classes + +@ifinfo + +Copyright (C) 1996 John W. Eaton. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of +a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for +modified versions. +@end ifinfo + +@titlepage +@title{Octave C++ Classes} +@subtitle{Edition 1.0 for Octave version @value{VERSION}} +@subtitle{September 1993} +@author{John W. Eaton} +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1996 John W. Eaton. + +This is the first edition of the documentation for Octave's C++ classes, +and is consistent with version @value{VERSION} of Octave. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the same conditions as for modified versions. +@end titlepage + +@ifinfo +@node Top, Acknowledgements, (dir), (dir) +@top + +This manual documents how to use, install and port Octave's C++ class +library, and how to report bugs. It corresponds to Octave version +@value{VERSION}. +@end ifinfo + +@c ------------------------------------------------------------------------ + +@menu +* Acknowledgements:: +* Copying:: +* Introduction:: +* Arrays:: +* Matrix and Vector @var{Operations}:: +* Matrix Factorizations:: +* Ranges:: +* Nonlinear Functions:: +* Objective Functions:: +* Quadrature:: +* Ordinary Differential Equations:: +* Installation:: +* Bugs:: +* Concept Index:: +* Function Index:: + + --- The Detailed Node Listing --- + +Acknowledgements + +* Contributors:: People who contributed to developing of Octave. + +Arrays + +* Constructors and Assignment:: +@end menu + +@include preface.texi +@include gpl.texi +@include intro.texi +@include array.texi +@include matvec.texi +@include factor.texi +@include range.texi +@include nleqn.texi +@include optim.texi +@include quad.texi +@include diffeq.texi +@include error.texi +@include install.texi +@include bugs.texi +@include cp-idx.texi +@include fn-idx.texi + +@contents + +@bye
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/matvec.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,1068 @@ +The real and complex @code{ColumnVector} and @code{RowVector} classes +all have the following functions. These will eventually be part of an +@code{MArray<T>} class, derived from the @code{Array<T>} class. Then +the @code{ColumnVector} and @code{RowVector} classes will be derived +from the @code{MArray<T>} class. + +Element by element vector by scalar ops. + +@deftypefn {} {RowVector} {operator +} (const RowVector &@var{a}, const double &@var{s}) +@deftypefnx {} {RowVector} {operator -} (const RowVector &@var{a}, const double &@var{s}) +@deftypefnx {} {RowVector} {operator *} (const RowVector &@var{a}, const double &@var{s}) +@deftypefnx {} {RowVector} {operator /} (const RowVector &@var{a}, const double &@var{s}) +@end deftypefn + +Element by element scalar by vector ops. + +@deftypefn {} {RowVector} {operator +} (const double &@var{s}, const RowVector &@var{a}) +@deftypefnx {} {RowVector} {operator -} (const double &@var{s}, const RowVector &@var{a}) +@deftypefnx {} {RowVector} {operator *} (const double &@var{s}, const RowVector &@var{a}) +@deftypefnx {} {RowVector} {operator /} (const double &@var{s}, const RowVector &@var{a}) +@end deftypefn + +Element by element vector by vector ops. + +@deftypefn {} {RowVector} {operator +} (const RowVector &@var{a}, const RowVector &@var{b}) +@deftypefnx {} {RowVector} {operator -} (const RowVector &@var{a}, const RowVector &@var{b}) +@end deftypefn + +@deftypefn {} {RowVector} product (const RowVector &@var{a}, const RowVector &@var{b}) +@deftypefnx {} {RowVector} quotient (const RowVector &@var{a}, const RowVector &@var{b}) +@end deftypefn + +Unary MArray ops. + +@deftypefn {} {RowVector} {operator -} (const RowVector &@var{a}) +@end deftypefn + +@c ------------------------------------------------------------------------ + +The @code{Matrix} classes share the following functions. These will +eventually be part of an @code{MArray2<T>} class, derived from the +@code{Array2<T>} class. Then the @code{Matrix} class will be derived +from the @code{MArray<T>} class. + +Element by element matrix by scalar ops. + +@deftypefn {} {Matrix} {operator +} (const Matrix &@var{a}, const double &@var{s}) +@deftypefnx {} {Matrix} {operator -} (const Matrix &@var{a}, const double &@var{s}) +@deftypefnx {} {Matrix} {operator *} (const Matrix &@var{a}, const double &@var{s}) +@deftypefnx {} {Matrix} {operator /} (const Matrix &@var{a}, const double &@var{s}) +@end deftypefn + +Element by element scalar by matrix ops. + +@deftypefn {} {Matrix} {operator +} (const double &@var{s}, const Matrix &@var{a}) +@deftypefnx {} {Matrix} {operator -} (const double &@var{s}, const Matrix &@var{a}) +@deftypefnx {} {Matrix} {operator *} (const double &@var{s}, const Matrix &@var{a}) +@deftypefnx {} {Matrix} {operator /} (const double &@var{s}, const Matrix &@var{a}) +@end deftypefn + +Element by element matrix by matrix ops. + +@deftypefn {} {Matrix} {operator +} (const Matrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {Matrix} {operator -} (const Matrix &@var{a}, const Matrix &@var{b}) +@end deftypefn + +@deftypefn {} {Matrix} product (const Matrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {Matrix} quotient (const Matrix &@var{a}, const Matrix &@var{b}) +@end deftypefn + +Unary matrix ops. + +@deftypefn {} {Matrix} {operator -} (const Matrix &@var{a}) +@end deftypefn + +@c ------------------------------------------------------------------------ + +The @code{DiagMatrix} classes share the following functions. These will +eventually be part of an @code{MDiagArray<T>} class, derived from the +@code{DiagArray<T>} class. Then the @code{DiagMatrix} class will be +derived from the @code{MDiagArray<T>} class. + +Element by element MDiagArray by scalar ops. + +@deftypefn {} {DiagMatrix} {operator *} (const DiagMatrix &@var{a}, const double &@var{s}) +@deftypefnx {} {DiagMatrix} {operator /} (const DiagMatrix &@var{a}, const double &@var{s}) +@end deftypefn + +Element by element scalar by MDiagArray ops. + +@deftypefn {} {DiagMatrix} {operator *} (const double &@var{s}, const DiagMatrix &@var{a}) +@end deftypefn + +Element by element MDiagArray by MDiagArray ops. + +@deftypefn {} {DiagMatrix} {operator +} (const DiagMatrix &@var{a}, const DiagMatrix &@var{b}) +@deftypefnx {} {DiagMatrix} {operator -} (const DiagMatrix &@var{a}, const DiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {DiagMatrix} product (const DiagMatrix &@var{a}, const DiagMatrix &@var{b}) +@end deftypefn + +Unary MDiagArray ops. + +@deftypefn {} {DiagMatrix} {operator -} (const DiagMatrix &@var{a}) +@end deftypefn + +@c ------------------------------------------------------------------------ + +@node Matrix and Vector @var{Operations}, Matrix Factorizations, Arrays, Top +@chapter Matrix and Vector Operations +@cindex matrix manipulations +@cindex vector manipulations + +@deftypefn {} {}Matrix (void) +@deftypefnx {} {}Matrix (int @var{r}, int @var{c}) +@deftypefnx {} {}Matrix (int @var{r}, int @var{c}, double @var{val}) +@deftypefnx {} {}Matrix (const Array2<double> &@var{a}) +@deftypefnx {} {}Matrix (const Matrix &@var{a}) +@deftypefnx {} {}Matrix (const DiagArray<double> &@var{a}) +@deftypefnx {} {}Matrix (const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} Matrix& {operator =} (const Matrix &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const Matrix &@var{a}) const +@deftypefnx {} int {operator !=} (const Matrix &@var{a}) const +@end deftypefn + +@deftypefn {} Matrix& insert (const Matrix &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} Matrix& insert (const RowVector &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} Matrix& insert (const ColumnVector &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} Matrix& insert (const DiagMatrix &@var{a}, int @var{r}, int @var{c}) +@end deftypefn + +@deftypefn {} Matrix& fill (double @var{val}) +@deftypefnx {} Matrix& fill (double @var{val}, int r1, int c1, int r2, int c2) +@end deftypefn + +@deftypefn {} Matrix append (const Matrix &@var{a}) const +@deftypefnx {} Matrix append (const RowVector &@var{a}) const +@deftypefnx {} Matrix append (const ColumnVector &@var{a}) const +@deftypefnx {} Matrix append (const DiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} Matrix stack (const Matrix &@var{a}) const +@deftypefnx {} Matrix stack (const RowVector &@var{a}) const +@deftypefnx {} Matrix stack (const ColumnVector &@var{a}) const +@deftypefnx {} Matrix stack (const DiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} Matrix transpose (void) const +@end deftypefn + +@deftypefn {} Matrix extract (int r1, int c1, int r2, int c2) const +@end deftypefn + +@deftypefn {} RowVector row (int @var{i}) const +@deftypefnx {} RowVector row (char *s) const +@end deftypefn + +@deftypefn {} ColumnVector column (int @var{i}) const +@deftypefnx {} ColumnVector column (char *s) const +@end deftypefn + +@deftypefn {} Matrix inverse (void) const +@deftypefnx {} Matrix inverse (int &@var{info}) const +@deftypefnx {} Matrix inverse (int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexMatrix fourier (void) const +@deftypefnx {} ComplexMatrix ifourier (void) const +@end deftypefn + +@deftypefn {} DET determinant (void) const +@deftypefnx {} DET determinant (int &@var{info}) const +@deftypefnx {} DET determinant (int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} Matrix solve (const Matrix &@var{b}) const +@deftypefnx {} Matrix solve (const Matrix &@var{b}, int &@var{info}) const +@deftypefnx {} Matrix solve (const Matrix &@var{b}, int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexMatrix solve (const ComplexMatrix &@var{b}) const +@deftypefnx {} ComplexMatrix solve (const ComplexMatrix &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexMatrix solve (const ComplexMatrix &@var{b}, int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ColumnVector solve (const ColumnVector &@var{b}) const +@deftypefnx {} ColumnVector solve (const ColumnVector &@var{b}, int &@var{info}) const +@deftypefnx {} ColumnVector solve (const ColumnVector &@var{b}, int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexColumnVector solve (const ComplexColumnVector &@var{b}) const +@deftypefnx {} ComplexColumnVector solve (const ComplexColumnVector &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexColumnVector solve (const ComplexColumnVector &@var{b}, int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} Matrix lssolve (const Matrix &@var{b}) const +@deftypefnx {} Matrix lssolve (const Matrix &@var{b}, int &@var{info}) const +@deftypefnx {} Matrix lssolve (const Matrix &@var{b}, int &@var{info}, int &@var{rank}) const +@end deftypefn + +@deftypefn {} ComplexMatrix lssolve (const ComplexMatrix &@var{b}) const +@deftypefnx {} ComplexMatrix lssolve (const ComplexMatrix &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexMatrix lssolve (const ComplexMatrix &@var{b}, int &@var{info}, int &@var{rank}) const +@end deftypefn + +@deftypefn {} ColumnVector lssolve (const ColumnVector &@var{b}) const +@deftypefnx {} ColumnVector lssolve (const ColumnVector &@var{b}, int &@var{info}) const +@deftypefnx {} ColumnVector lssolve (const ColumnVector &@var{b}, int &@var{info}, int &@var{rank}) const +@end deftypefn + +@deftypefn {} ComplexColumnVector lssolve (const ComplexColumnVector &@var{b}) const +@deftypefnx {} ComplexColumnVector lssolve (const ComplexColumnVector &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexColumnVector lssolve (const ComplexColumnVector &@var{b}, int &@var{info}, int &@var{rank}) const +@end deftypefn + +@deftypefn {} Matrix& {operator +=} (const Matrix &@var{a}) +@deftypefnx {} Matrix& {operator -=} (const Matrix &@var{a}) +@end deftypefn + +@deftypefn {} Matrix& {operator +=} (const DiagMatrix &@var{a}) +@deftypefnx {} Matrix& {operator -=} (const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} Matrix {operator !} (void) const +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const Matrix &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexMatrix} {operator -} (const Matrix &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexMatrix} {operator *} (const Matrix &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexMatrix} {operator /} (const Matrix &@var{a}, const Complex &@var{s}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const Complex &@var{s}, const Matrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator -} (const Complex &@var{s}, const Matrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator *} (const Complex &@var{s}, const Matrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator /} (const Complex &@var{s}, const Matrix &@var{a}) +@end deftypefn + +@deftypefn {} {ColumnVector} {operator *} (const Matrix &@var{a}, const ColumnVector &@var{b}) +@deftypefnx {} {ComplexColumnVector} {operator *} (const Matrix &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {Matrix} {operator +} (const Matrix &@var{a}, const DiagMatrix &@var{b}) +@deftypefnx {} {Matrix} {operator -} (const Matrix &@var{a}, const DiagMatrix &@var{b}) +@deftypefnx {} {Matrix} {operator *} (const Matrix &@var{a}, const DiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const Matrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const Matrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const Matrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {Matrix} {operator *} (const Matrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const Matrix &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const Matrix &@var{a}, const ComplexMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const Matrix &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} product (const Matrix &@var{a}, const ComplexMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} quotient (const Matrix &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {Matrix} map (d_d_Mapper @var{f}, const Matrix &@var{a}) +@deftypefnx {} void map (d_d_Mapper @var{f}) +@end deftypefn + +@deftypefn {} Matrix all (void) const +@deftypefnx {} Matrix any (void) const +@end deftypefn + +@deftypefn {} Matrix cumprod (void) const +@deftypefnx {} Matrix cumsum (void) const +@deftypefnx {} Matrix prod (void) const +@deftypefnx {} Matrix sum (void) const +@deftypefnx {} Matrix sumsq (void) const +@end deftypefn + +@deftypefn {} ColumnVector diag (void) const +@deftypefnx {} ColumnVector diag (int @var{k}) const +@end deftypefn + +@deftypefn {} ColumnVector row_min (void) const +@deftypefnx {} ColumnVector row_min_loc (void) const +@end deftypefn + +@deftypefn {} ColumnVector row_max (void) const +@deftypefnx {} ColumnVector row_max_loc (void) const +@end deftypefn + +@deftypefn {} RowVector column_min (void) const +@deftypefnx {} RowVector column_min_loc (void) const +@end deftypefn + +@deftypefn {} RowVector column_max (void) const +@deftypefnx {} RowVector column_max_loc (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const Matrix &@var{a}) +@deftypefnx {} {istream&} {operator >>} (istream &@var{is}, Matrix &@var{a}) +@end deftypefn + +@deftypefn {} {}ColumnVector (void) +@deftypefnx {} {}ColumnVector (int @var{n}) +@deftypefnx {} {}ColumnVector (int @var{n}, double @var{val}) +@deftypefnx {} {}ColumnVector (const Array<double> &@var{a}) +@deftypefnx {} {}ColumnVector (const ColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} ColumnVector& {operator =} (const ColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const ColumnVector &@var{a}) const +@deftypefnx {} int {operator !=} (const ColumnVector &@var{a}) const +@end deftypefn + +@deftypefn {} ColumnVector& insert (const ColumnVector &@var{a}, int @var{r}) +@end deftypefn + +@deftypefn {} ColumnVector& fill (double @var{val}) +@deftypefnx {} ColumnVector& fill (double @var{val}, int r1, int r2) +@end deftypefn + +@deftypefn {} ColumnVector stack (const ColumnVector &@var{a}) const +@end deftypefn + +@deftypefn {} RowVector transpose (void) const +@end deftypefn + +@deftypefn {} ColumnVector extract (int r1, int r2) const +@end deftypefn + +@deftypefn {} ColumnVector& {operator +=} (const ColumnVector &@var{a}) +@deftypefnx {} ColumnVector& {operator -=} (const ColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator +} (const ColumnVector &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexColumnVector} {operator -} (const ColumnVector &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexColumnVector} {operator *} (const ColumnVector &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexColumnVector} {operator /} (const ColumnVector &@var{a}, const Complex &@var{s}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator +} (const Complex &@var{s}, const ColumnVector &@var{a}) +@deftypefnx {} {ComplexColumnVector} {operator -} (const Complex &@var{s}, const ColumnVector &@var{a}) +@deftypefnx {} {ComplexColumnVector} {operator *} (const Complex &@var{s}, const ColumnVector &@var{a}) +@deftypefnx {} {ComplexColumnVector} {operator /} (const Complex &@var{s}, const ColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} {Matrix} {operator *} (const ColumnVector &@var{a}, const RowVector &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator *} (const ColumnVector &@var{a}, const ComplexRowVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator +} (const ComplexColumnVector &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator -} (const ComplexColumnVector &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} product (const ComplexColumnVector &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} quotient (const ComplexColumnVector &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ColumnVector} map (d_d_Mapper @var{f}, const ColumnVector &@var{a}) +@deftypefnx {} void map (d_d_Mapper @var{f}) +@end deftypefn + +@deftypefn {} double min (void) const +@deftypefnx {} double max (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} {}RowVector (void) +@deftypefnx {} {}RowVector (int @var{n}) +@deftypefnx {} {}RowVector (int @var{n}, double @var{val}) +@deftypefnx {} {}RowVector (const Array<double> &@var{a}) +@deftypefnx {} {}RowVector (const RowVector &@var{a}) +@end deftypefn + +@deftypefn {} RowVector& {operator =} (const RowVector &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const RowVector &@var{a}) const +@deftypefnx {} int {operator !=} (const RowVector &@var{a}) const +@end deftypefn + +@deftypefn {} RowVector& insert (const RowVector &@var{a}, int @var{c}) +@end deftypefn + +@deftypefn {} RowVector& fill (double @var{val}) +@deftypefnx {} RowVector& fill (double @var{val}, int c1, int c2) +@end deftypefn + +@deftypefn {} RowVector append (const RowVector &@var{a}) const +@end deftypefn + +@deftypefn {} ColumnVector transpose (void) const +@end deftypefn + +@deftypefn {} RowVector extract (int c1, int c2) const +@end deftypefn + +@deftypefn {} RowVector& {operator +=} (const RowVector &@var{a}) +@deftypefnx {} RowVector& {operator -=} (const RowVector &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator +} (const RowVector &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexRowVector} {operator -} (const RowVector &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexRowVector} {operator *} (const RowVector &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexRowVector} {operator /} (const RowVector &@var{a}, const Complex &@var{s}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator +} (const Complex &@var{s}, const RowVector &@var{a}) +@deftypefnx {} {ComplexRowVector} {operator -} (const Complex &@var{s}, const RowVector &@var{a}) +@deftypefnx {} {ComplexRowVector} {operator *} (const Complex &@var{s}, const RowVector &@var{a}) +@deftypefnx {} {ComplexRowVector} {operator /} (const Complex &@var{s}, const RowVector &@var{a}) +@end deftypefn + +@deftypefn {} {double} {operator *} (const RowVector &@var{a}, ColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {Complex} {operator *} (const RowVector &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {RowVector} {operator *} (const RowVector &@var{a}, const Matrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator *} (const RowVector &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator +} (const RowVector &@var{a}, const ComplexRowVector &@var{b}) +@deftypefnx {} {ComplexRowVector} {operator -} (const RowVector &@var{a}, const ComplexRowVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} product (const RowVector &@var{a}, const ComplexRowVector &@var{b}) +@deftypefnx {} {ComplexRowVector} quotient (const RowVector &@var{a}, const ComplexRowVector &@var{b}) +@end deftypefn + +@deftypefn {} {RowVector} map (d_d_Mapper @var{f}, const RowVector &@var{a}) +@deftypefnx {} void map (d_d_Mapper @var{f}) +@end deftypefn + +@deftypefn {} double min (void) const +@deftypefnx {} double max (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const RowVector &@var{a}) +@end deftypefn + +@deftypefn {} {}DiagMatrix (void) +@deftypefnx {} {}DiagMatrix (int @var{n}) +@deftypefnx {} {}DiagMatrix (int @var{n}, double @var{val}) +@deftypefnx {} {}DiagMatrix (int @var{r}, int @var{c}) +@deftypefnx {} {}DiagMatrix (int @var{r}, int @var{c}, double @var{val}) +@deftypefnx {} {}DiagMatrix (const RowVector &@var{a}) +@deftypefnx {} {}DiagMatrix (const ColumnVector &@var{a}) +@deftypefnx {} {}DiagMatrix (const DiagArray<double> &@var{a}) +@deftypefnx {} {}DiagMatrix (const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} DiagMatrix& {operator =} (const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const DiagMatrix &@var{a}) const +@deftypefnx {} int {operator !=} (const DiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} DiagMatrix& fill (double @var{val}) +@deftypefnx {} DiagMatrix& fill (double @var{val}, int @var{beg}, int @var{end}) +@deftypefnx {} DiagMatrix& fill (const ColumnVector &@var{a}) +@deftypefnx {} DiagMatrix& fill (const RowVector &@var{a}) +@deftypefnx {} DiagMatrix& fill (const ColumnVector &@var{a}, int @var{beg}) +@deftypefnx {} DiagMatrix& fill (const RowVector &@var{a}, int @var{beg}) +@end deftypefn + +@deftypefn {} DiagMatrix transpose (void) const +@end deftypefn + +@deftypefn {} Matrix extract (int r1, int c1, int r2, int c2) const +@end deftypefn + +@deftypefn {} RowVector row (int @var{i}) const +@deftypefnx {} RowVector row (char *s) const +@end deftypefn + +@deftypefn {} ColumnVector column (int @var{i}) const +@deftypefnx {} ColumnVector column (char *s) const +@end deftypefn + +@deftypefn {} DiagMatrix inverse (void) const +@deftypefnx {} DiagMatrix inverse (int &@var{info}) const +@end deftypefn + +@deftypefn {} DiagMatrix& {operator +=} (const DiagMatrix &@var{a}) +@deftypefnx {} DiagMatrix& {operator -=} (const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {Matrix} {operator +} (const DiagMatrix &@var{a}, double @var{s}) +@deftypefnx {} {Matrix} {operator -} (const DiagMatrix &@var{a}, double @var{s}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const DiagMatrix &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexMatrix} {operator -} (const DiagMatrix &@var{a}, const Complex &@var{s}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} {operator *} (const DiagMatrix &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexDiagMatrix} {operator /} (const DiagMatrix &@var{a}, const Complex &@var{s}) +@end deftypefn + +@deftypefn {} {Matrix} {operator +} (double @var{s}, const DiagMatrix &@var{a}) +@deftypefnx {} {Matrix} {operator -} (double @var{s}, const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const Complex &@var{s}, const DiagMatrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator -} (const Complex &@var{s}, const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} {operator *} (const Complex &@var{s}, const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ColumnVector} {operator *} (const DiagMatrix &@var{a}, const ColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator *} (const DiagMatrix &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} {operator +} (const DiagMatrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@deftypefnx {} {ComplexDiagMatrix} {operator -} (const DiagMatrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} product (const DiagMatrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {Matrix} {operator +} (const DiagMatrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {Matrix} {operator -} (const DiagMatrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {Matrix} {operator *} (const DiagMatrix &@var{a}, const Matrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const DiagMatrix &@var{a}, const ComplexMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const DiagMatrix &@var{a}, const ComplexMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const DiagMatrix &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} ColumnVector diag (void) const +@deftypefnx {} ColumnVector diag (int @var{k}) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexMatrix (void) +@deftypefnx {} {}ComplexMatrix (int @var{r}, int @var{c}) +@deftypefnx {} {}ComplexMatrix (int @var{r}, int @var{c}, const Complex &@var{val}) +@deftypefnx {} {}ComplexMatrix (const Matrix &@var{a}) +@deftypefnx {} {}ComplexMatrix (const Array2<Complex> &@var{a}) +@deftypefnx {} {}ComplexMatrix (const ComplexMatrix &@var{a}) +@deftypefnx {} {}ComplexMatrix (const DiagMatrix &@var{a}) +@deftypefnx {} {}ComplexMatrix (const DiagArray<Complex> &@var{a}) +@deftypefnx {} {}ComplexMatrix (const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix& {operator =} (const ComplexMatrix &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const ComplexMatrix &@var{a}) const +@deftypefnx {} int {operator !=} (const ComplexMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexMatrix& insert (const Matrix &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} ComplexMatrix& insert (const RowVector &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} ComplexMatrix& insert (const ColumnVector &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} ComplexMatrix& insert (const DiagMatrix &@var{a}, int @var{r}, int @var{c}) +@end deftypefn + +@deftypefn {} ComplexMatrix& insert (const ComplexMatrix &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} ComplexMatrix& insert (const ComplexRowVector &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} ComplexMatrix& insert (const ComplexColumnVector &@var{a}, int @var{r}, int @var{c}) +@deftypefnx {} ComplexMatrix& insert (const ComplexDiagMatrix &@var{a}, int @var{r}, int @var{c}) +@end deftypefn + +@deftypefn {} ComplexMatrix& fill (double @var{val}) +@deftypefnx {} ComplexMatrix& fill (const Complex &@var{val}) +@deftypefnx {} ComplexMatrix& fill (double @var{val}, int r1, int c1, int r2, int c2) +@deftypefnx {} ComplexMatrix& fill (const Complex &@var{val}, int r1, int c1, int r2, int c2) +@end deftypefn + +@deftypefn {} ComplexMatrix append (const Matrix &@var{a}) const +@deftypefnx {} ComplexMatrix append (const RowVector &@var{a}) const +@deftypefnx {} ComplexMatrix append (const ColumnVector &@var{a}) const +@deftypefnx {} ComplexMatrix append (const DiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexMatrix append (const ComplexMatrix &@var{a}) const +@deftypefnx {} ComplexMatrix append (const ComplexRowVector &@var{a}) const +@deftypefnx {} ComplexMatrix append (const ComplexColumnVector &@var{a}) const +@deftypefnx {} ComplexMatrix append (const ComplexDiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexMatrix stack (const Matrix &@var{a}) const +@deftypefnx {} ComplexMatrix stack (const RowVector &@var{a}) const +@deftypefnx {} ComplexMatrix stack (const ColumnVector &@var{a}) const +@deftypefnx {} ComplexMatrix stack (const DiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexMatrix stack (const ComplexMatrix &@var{a}) const +@deftypefnx {} ComplexMatrix stack (const ComplexRowVector &@var{a}) const +@deftypefnx {} ComplexMatrix stack (const ComplexColumnVector &@var{a}) const +@deftypefnx {} ComplexMatrix stack (const ComplexDiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexMatrix transpose (void) const +@end deftypefn + +@deftypefn {} {Matrix} real (const ComplexMatrix &@var{a}) +@deftypefnx {} {Matrix} imag (const ComplexMatrix &@var{a}) +@deftypefnx {} {ComplexMatrix} conj (const ComplexMatrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix extract (int r1, int c1, int r2, int c2) const +@end deftypefn + +@deftypefn {} ComplexRowVector row (int @var{i}) const +@deftypefnx {} ComplexRowVector row (char *s) const +@end deftypefn + +@deftypefn {} ComplexColumnVector column (int @var{i}) const +@deftypefnx {} ComplexColumnVector column (char *s) const +@end deftypefn + +@deftypefn {} ComplexMatrix inverse (void) const +@deftypefnx {} ComplexMatrix inverse (int &@var{info}) const +@deftypefnx {} ComplexMatrix inverse (int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexMatrix fourier (void) const +@deftypefnx {} ComplexMatrix ifourier (void) const +@end deftypefn + +@deftypefn {} ComplexDET determinant (void) const +@deftypefnx {} ComplexDET determinant (int &@var{info}) const +@deftypefnx {} ComplexDET determinant (int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexMatrix solve (const Matrix &@var{b}) const +@deftypefnx {} ComplexMatrix solve (const Matrix &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexMatrix solve (const Matrix &@var{b}, int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexMatrix solve (const ComplexMatrix &@var{b}) const +@deftypefnx {} ComplexMatrix solve (const ComplexMatrix &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexMatrix solve (const ComplexMatrix &@var{b}, int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexColumnVector solve (const ComplexColumnVector &@var{b}) const +@deftypefnx {} ComplexColumnVector solve (const ComplexColumnVector &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexColumnVector solve (const ComplexColumnVector &@var{b}, int &@var{info}, double &@var{rcond}) const +@end deftypefn + +@deftypefn {} ComplexMatrix lssolve (const ComplexMatrix &@var{b}) const +@deftypefnx {} ComplexMatrix lssolve (const ComplexMatrix &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexMatrix lssolve (const ComplexMatrix &@var{b}, int &@var{info}, int &@var{rank}) const +@end deftypefn + +@deftypefn {} ComplexColumnVector lssolve (const ComplexColumnVector &@var{b}) const +@deftypefnx {} ComplexColumnVector lssolve (const ComplexColumnVector &@var{b}, int &@var{info}) const +@deftypefnx {} ComplexColumnVector lssolve (const ComplexColumnVector &@var{b}, int &@var{info}, int &@var{rank}) const +@end deftypefn + +@deftypefn {} ComplexMatrix& {operator +=} (const DiagMatrix &@var{a}) +@deftypefnx {} ComplexMatrix& {operator -=} (const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix& {operator +=} (const ComplexDiagMatrix &@var{a}) +@deftypefnx {} ComplexMatrix& {operator -=} (const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix& {operator +=} (const Matrix &@var{a}) +@deftypefnx {} ComplexMatrix& {operator -=} (const Matrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix& {operator +=} (const ComplexMatrix &@var{a}) +@deftypefnx {} ComplexMatrix& {operator -=} (const ComplexMatrix &@var{a}) +@end deftypefn + +@deftypefn {} Matrix {operator !} (void) const +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexMatrix &@var{a}, double @var{s}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexMatrix &@var{a}, double @var{s}) +@deftypefnx {} {ComplexMatrix} {operator *} (const ComplexMatrix &@var{a}, double @var{s}) +@deftypefnx {} {ComplexMatrix} {operator /} (const ComplexMatrix &@var{a}, double @var{s}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (double @var{s}, const ComplexMatrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator -} (double @var{s}, const ComplexMatrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator *} (double @var{s}, const ComplexMatrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator /} (double @var{s}, const ComplexMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator *} (const ComplexMatrix &@var{a}, const ColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator *} (const ComplexMatrix &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexMatrix &@var{a}, const DiagMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexMatrix &@var{a}, const DiagMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const ComplexMatrix &@var{a}, const DiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexMatrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexMatrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const ComplexMatrix &@var{a}, const ComplexDiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexMatrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexMatrix &@var{a}, const Matrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator *} (const ComplexMatrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const ComplexMatrix &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} product (const ComplexMatrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {ComplexMatrix} quotient (const ComplexMatrix &@var{a}, const Matrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} map (c_c_Mapper @var{f}, const ComplexMatrix &@var{a}) +@deftypefnx {} {Matrix} map (d_c_Mapper @var{f}, const ComplexMatrix &@var{a}) +@deftypefnx {} void map (c_c_Mapper @var{f}) +@end deftypefn + +@deftypefn {} Matrix all (void) const +@deftypefnx {} Matrix any (void) const +@end deftypefn + +@deftypefn {} ComplexMatrix cumprod (void) const +@deftypefnx {} ComplexMatrix cumsum (void) const +@deftypefnx {} ComplexMatrix prod (void) const +@deftypefnx {} ComplexMatrix sum (void) const +@deftypefnx {} ComplexMatrix sumsq (void) const +@end deftypefn + +@deftypefn {} ComplexColumnVector diag (void) const +@deftypefnx {} ComplexColumnVector diag (int @var{k}) const +@end deftypefn + +@deftypefn {} ComplexColumnVector row_min (void) const +@deftypefnx {} ComplexColumnVector row_min_loc (void) const +@end deftypefn + +@deftypefn {} ComplexColumnVector row_max (void) const +@deftypefnx {} ComplexColumnVector row_max_loc (void) const +@end deftypefn + +@deftypefn {} ComplexRowVector column_min (void) const +@deftypefnx {} ComplexRowVector column_min_loc (void) const +@end deftypefn + +@deftypefn {} ComplexRowVector column_max (void) const +@deftypefnx {} ComplexRowVector column_max_loc (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexMatrix &@var{a}) +@deftypefnx {} {istream&} {operator >>} (istream &@var{is}, ComplexMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexColumnVector (void) +@deftypefnx {} {}ComplexColumnVector (int @var{n}) +@deftypefnx {} {}ComplexColumnVector (int @var{n}, const Complex &@var{val}) +@deftypefnx {} {}ComplexColumnVector (const ColumnVector &@var{a}) +@deftypefnx {} {}ComplexColumnVector (const Array<Complex> &@var{a}) +@deftypefnx {} {}ComplexColumnVector (const ComplexColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} ComplexColumnVector& {operator =} (const ComplexColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const ComplexColumnVector &@var{a}) const +@deftypefnx {} int {operator !=} (const ComplexColumnVector &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexColumnVector& insert (const ColumnVector &@var{a}, int @var{r}) +@deftypefnx {} ComplexColumnVector& insert (const ComplexColumnVector &@var{a}, int @var{r}) +@end deftypefn + +@deftypefn {} ComplexColumnVector& fill (double @var{val}) +@deftypefnx {} ComplexColumnVector& fill (const Complex &@var{val}) +@deftypefnx {} ComplexColumnVector& fill (double @var{val}, int r1, int r2) +@deftypefnx {} ComplexColumnVector& fill (const Complex &@var{val}, int r1, int r2) +@end deftypefn + +@deftypefn {} ComplexColumnVector stack (const ColumnVector &@var{a}) const +@deftypefnx {} ComplexColumnVector stack (const ComplexColumnVector &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexRowVector transpose (void) const +@end deftypefn + +@deftypefn {} {ColumnVector} real (const ComplexColumnVector &@var{a}) +@deftypefnx {} {ColumnVector} imag (const ComplexColumnVector &@var{a}) +@deftypefnx {} {ComplexColumnVector} conj (const ComplexColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} ComplexColumnVector extract (int r1, int r2) const +@end deftypefn + +@deftypefn {} ComplexColumnVector& {operator +=} (const ColumnVector &@var{a}) +@deftypefnx {} ComplexColumnVector& {operator -=} (const ColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} ComplexColumnVector& {operator +=} (const ComplexColumnVector &@var{a}) +@deftypefnx {} ComplexColumnVector& {operator -=} (const ComplexColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator +} (const ComplexColumnVector &@var{a}, double @var{s}) +@deftypefnx {} {ComplexColumnVector} {operator -} (const ComplexColumnVector &@var{a}, double @var{s}) +@deftypefnx {} {ComplexColumnVector} {operator *} (const ComplexColumnVector &@var{a}, double @var{s}) +@deftypefnx {} {ComplexColumnVector} {operator /} (const ComplexColumnVector &@var{a}, double @var{s}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator +} (double @var{s}, const ComplexColumnVector &@var{a}) +@deftypefnx {} {ComplexColumnVector} {operator -} (double @var{s}, const ComplexColumnVector &@var{a}) +@deftypefnx {} {ComplexColumnVector} {operator *} (double @var{s}, const ComplexColumnVector &@var{a}) +@deftypefnx {} {ComplexColumnVector} {operator /} (double @var{s}, const ComplexColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator *} (const ComplexColumnVector &@var{a}, const ComplexRowVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator +} (const ComplexColumnVector &@var{a}, const ColumnVector &@var{b}) +@deftypefnx {} {ComplexColumnVector} {operator -} (const ComplexColumnVector &@var{a}, const ColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} product (const ComplexColumnVector &@var{a}, const ColumnVector &@var{b}) +@deftypefnx {} {ComplexColumnVector} quotient (const ComplexColumnVector &@var{a}, const ColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} map (c_c_Mapper @var{f}, const ComplexColumnVector &@var{a}) +@deftypefnx {} {ColumnVector} map (d_c_Mapper @var{f}, const ComplexColumnVector &@var{a}) +@deftypefnx {} void map (c_c_Mapper @var{f}) +@end deftypefn + +@deftypefn {} Complex min (void) const +@deftypefnx {} Complex max (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexColumnVector &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexRowVector (void) +@deftypefnx {} {}ComplexRowVector (int @var{n}) +@deftypefnx {} {}ComplexRowVector (int @var{n}, const Complex &@var{val}) +@deftypefnx {} {}ComplexRowVector (const RowVector &@var{a}) +@deftypefnx {} {}ComplexRowVector (const Array<Complex> &@var{a}) +@deftypefnx {} {}ComplexRowVector (const ComplexRowVector &@var{a}) +@end deftypefn + +@deftypefn {} ComplexRowVector& {operator =} (const ComplexRowVector &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const ComplexRowVector &@var{a}) const +@deftypefnx {} int {operator !=} (const ComplexRowVector &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexRowVector& insert (const RowVector &@var{a}, int @var{c}) +@deftypefnx {} ComplexRowVector& insert (const ComplexRowVector &@var{a}, int @var{c}) +@end deftypefn + +@deftypefn {} ComplexRowVector& fill (double @var{val}) +@deftypefnx {} ComplexRowVector& fill (const Complex &@var{val}) +@deftypefnx {} ComplexRowVector& fill (double @var{val}, int c1, int c2) +@deftypefnx {} ComplexRowVector& fill (const Complex &@var{val}, int c1, int c2) +@end deftypefn + +@deftypefn {} ComplexRowVector append (const RowVector &@var{a}) const +@deftypefnx {} ComplexRowVector append (const ComplexRowVector &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexColumnVector transpose (void) const +@end deftypefn + +@deftypefn {} {RowVector} real (const ComplexRowVector &@var{a}) +@deftypefnx {} {RowVector} imag (const ComplexRowVector &@var{a}) +@deftypefnx {} {ComplexRowVector} conj (const ComplexRowVector &@var{a}) +@end deftypefn + +@deftypefn {} ComplexRowVector extract (int c1, int c2) const +@end deftypefn + +@deftypefn {} ComplexRowVector& {operator +=} (const RowVector &@var{a}) +@deftypefnx {} ComplexRowVector& {operator -=} (const RowVector &@var{a}) +@end deftypefn + +@deftypefn {} ComplexRowVector& {operator +=} (const ComplexRowVector &@var{a}) +@deftypefnx {} ComplexRowVector& {operator -=} (const ComplexRowVector &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator +} (const ComplexRowVector &@var{a}, double @var{s}) +@deftypefnx {} {ComplexRowVector} {operator -} (const ComplexRowVector &@var{a}, double @var{s}) +@deftypefnx {} {ComplexRowVector} {operator *} (const ComplexRowVector &@var{a}, double @var{s}) +@deftypefnx {} {ComplexRowVector} {operator /} (const ComplexRowVector &@var{a}, double @var{s}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator +} (double @var{s}, const ComplexRowVector &@var{a}) +@deftypefnx {} {ComplexRowVector} {operator -} (double @var{s}, const ComplexRowVector &@var{a}) +@deftypefnx {} {ComplexRowVector} {operator *} (double @var{s}, const ComplexRowVector &@var{a}) +@deftypefnx {} {ComplexRowVector} {operator /} (double @var{s}, const ComplexRowVector &@var{a}) +@end deftypefn + +@deftypefn {} {Complex} {operator *} (const ComplexRowVector &@var{a}, const ColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {Complex} {operator *} (const ComplexRowVector &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator *} (const ComplexRowVector &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} {operator +} (const ComplexRowVector &@var{a}, const RowVector &@var{b}) +@deftypefnx {} {ComplexRowVector} {operator -} (const ComplexRowVector &@var{a}, const RowVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} product (const ComplexRowVector &@var{a}, const RowVector &@var{b}) +@deftypefnx {} {ComplexRowVector} quotient (const ComplexRowVector &@var{a}, const RowVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexRowVector} map (c_c_Mapper @var{f}, const ComplexRowVector &@var{a}) +@deftypefnx {} {RowVector} map (d_c_Mapper @var{f}, const ComplexRowVector &@var{a}) +@deftypefnx {} void map (c_c_Mapper @var{f}) +@end deftypefn + +@deftypefn {} Complex min (void) const +@deftypefnx {} Complex max (void) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexRowVector &@var{a}) +@end deftypefn + +@deftypefn {} {}ComplexDiagMatrix (void) +@deftypefnx {} {}ComplexDiagMatrix (int @var{n}) +@deftypefnx {} {}ComplexDiagMatrix (int @var{n}, const Complex &@var{val}) +@deftypefnx {} {}ComplexDiagMatrix (int @var{r}, int @var{c}) +@deftypefnx {} {}ComplexDiagMatrix (int @var{r}, int @var{c}, const Complex &@var{val}) +@deftypefnx {} {}ComplexDiagMatrix (const RowVector &@var{a}) +@deftypefnx {} {}ComplexDiagMatrix (const ComplexRowVector &@var{a}) +@deftypefnx {} {}ComplexDiagMatrix (const ColumnVector &@var{a}) +@deftypefnx {} {}ComplexDiagMatrix (const ComplexColumnVector &@var{a}) +@deftypefnx {} {}ComplexDiagMatrix (const DiagMatrix &@var{a}) +@deftypefnx {} {}ComplexDiagMatrix (const DiagArray<Complex> &@var{a}) +@deftypefnx {} {}ComplexDiagMatrix (const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexDiagMatrix& {operator =} (const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} int {operator ==} (const ComplexDiagMatrix &@var{a}) const +@deftypefnx {} int {operator !=} (const ComplexDiagMatrix &@var{a}) const +@end deftypefn + +@deftypefn {} ComplexDiagMatrix& fill (double @var{val}) +@deftypefnx {} ComplexDiagMatrix& fill (const Complex &@var{val}) +@deftypefnx {} ComplexDiagMatrix& fill (double @var{val}, int @var{beg}, int @var{end}) +@deftypefnx {} ComplexDiagMatrix& fill (const Complex &@var{val}, int @var{beg}, int @var{end}) +@deftypefnx {} ComplexDiagMatrix& fill (const ColumnVector &@var{a}) +@deftypefnx {} ComplexDiagMatrix& fill (const ComplexColumnVector &@var{a}) +@deftypefnx {} ComplexDiagMatrix& fill (const RowVector &@var{a}) +@deftypefnx {} ComplexDiagMatrix& fill (const ComplexRowVector &@var{a}) +@deftypefnx {} ComplexDiagMatrix& fill (const ColumnVector &@var{a}, int @var{beg}) +@deftypefnx {} ComplexDiagMatrix& fill (const ComplexColumnVector &@var{a}, int @var{beg}) +@deftypefnx {} ComplexDiagMatrix& fill (const RowVector &@var{a}, int @var{beg}) +@deftypefnx {} ComplexDiagMatrix& fill (const ComplexRowVector &@var{a}, int @var{beg}) +@end deftypefn + +@deftypefn {} ComplexDiagMatrix transpose (void) const +@end deftypefn + +@deftypefn {} {DiagMatrix} real (const ComplexDiagMatrix &@var{a}) +@deftypefnx {} {DiagMatrix} imag (const ComplexDiagMatrix &@var{a}) +@deftypefnx {} {ComplexDiagMatrix} conj (const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexMatrix extract (int r1, int c1, int r2, int c2) const +@end deftypefn + +@deftypefn {} ComplexRowVector row (int @var{i}) const +@deftypefnx {} ComplexRowVector row (char *s) const +@end deftypefn + +@deftypefn {} ComplexColumnVector column (int @var{i}) const +@deftypefnx {} ComplexColumnVector column (char *s) const +@end deftypefn + +@deftypefn {} ComplexDiagMatrix inverse (int &@var{info}) const +@deftypefnx {} ComplexDiagMatrix inverse (void) const +@end deftypefn + +@deftypefn {} ComplexDiagMatrix& {operator +=} (const DiagMatrix &@var{a}) +@deftypefnx {} ComplexDiagMatrix& {operator -=} (const DiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} ComplexDiagMatrix& {operator +=} (const ComplexDiagMatrix &@var{a}) +@deftypefnx {} ComplexDiagMatrix& {operator -=} (const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexDiagMatrix &@var{a}, double @var{s}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexDiagMatrix &@var{a}, double @var{s}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexDiagMatrix &@var{a}, const Complex &@var{s}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexDiagMatrix &@var{a}, const Complex &@var{s}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} {operator *} (const ComplexDiagMatrix &@var{a}, double @var{s}) +@deftypefnx {} {ComplexDiagMatrix} {operator /} (const ComplexDiagMatrix &@var{a}, double @var{s}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (double @var{s}, const ComplexDiagMatrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator -} (double @var{s}, const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const Complex &@var{s}, const ComplexDiagMatrix &@var{a}) +@deftypefnx {} {ComplexMatrix} {operator -} (const Complex &@var{s}, const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} {operator *} (double @var{s}, const ComplexDiagMatrix &@var{a}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator *} (const ComplexDiagMatrix &@var{a}, const ColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexColumnVector} {operator *} (const ComplexDiagMatrix &@var{a}, const ComplexColumnVector &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} {operator +} (const ComplexDiagMatrix &@var{a}, const DiagMatrix &@var{b}) +@deftypefnx {} {ComplexDiagMatrix} {operator -} (const ComplexDiagMatrix &@var{a}, const DiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexDiagMatrix} product (const ComplexDiagMatrix &@var{a}, const DiagMatrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexDiagMatrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexDiagMatrix &@var{a}, const Matrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const ComplexDiagMatrix &@var{a}, const Matrix &@var{b}) +@end deftypefn + +@deftypefn {} {ComplexMatrix} {operator +} (const ComplexDiagMatrix &@var{a}, const ComplexMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator -} (const ComplexDiagMatrix &@var{a}, const ComplexMatrix &@var{b}) +@deftypefnx {} {ComplexMatrix} {operator *} (const ComplexDiagMatrix &@var{a}, const ComplexMatrix &@var{b}) +@end deftypefn + +@deftypefn {} ComplexColumnVector diag (void) const +@deftypefnx {} ComplexColumnVector diag (int @var{k}) const +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const ComplexDiagMatrix &@var{a}) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/nleqn.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,78 @@ +@node Nonlinear Functions, Objective Functions, Ranges, Top +@chapter Nonlinear Functions +@cindex nonlinear functions + +@deftypefn {} {}NLFunc (void) +@deftypefnx {} {}NLFunc (const @var{nonlinear_fcn}) +@deftypefnx {} {}NLFunc (const @var{nonlinear_fcn}, const @var{jacobian_fcn}) +@deftypefnx {} {}NLFunc (const NLFunc &@var{a}) +@end deftypefn + +@deftypefn {} NLFunc& {operator =} (const NLFunc &@var{a}) +@end deftypefn + +@deftypefn {} nonlinear_fcn function (void) const; +@end deftypefn + +@deftypefn {} NLFunc& set_function (const nonlinear_fcn @var{f}) +@end deftypefn + +@deftypefn {} jacobian_fcn jacobian_function (void) const; +@end deftypefn + +@deftypefn {} NLFunc& set_jacobian_function (const jacobian_fcn @var{j}) +@end deftypefn + +@node Nonlinear Equations, , Nonlinear Functions +@chapter Nonlinear Equations +@cindex nonlinear equations + +@deftypefn {} {}NLEqn_options (void) +@deftypefnx {} {}NLEqn_options (const NLEqn_options &@var{opt}) +@end deftypefn + +@deftypefn {} NLEqn_options& {operator =} (const NLEqn_options &@var{opt}) +@end deftypefn + +@deftypefn {} void init (void) +@end deftypefn + +@deftypefn {} void copy (const NLEqn_options &@var{opt}) +@end deftypefn + +@deftypefn {} void set_default_options (void) +@end deftypefn + +@deftypefn {} void set_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} double tolerance (void) +@end deftypefn + +@deftypefn {} {}NLEqn (void) +@deftypefnx {} {}NLEqn (const ColumnVector&, const @var{NLFunc}) +@deftypefnx {} {}NLEqn (const NLEqn &@var{a}) +@end deftypefn + +@deftypefn {} NLEqn& {operator =} (const NLEqn &@var{a}) +@end deftypefn + +@deftypefn {} void resize (int @var{n}) +@end deftypefn + +@deftypefn {} void set_states (const ColumnVector &@var{x}) +@end deftypefn + +@deftypefn {} ColumnVector states (void) const +@end deftypefn + +@deftypefn {} int size (void) const +@end deftypefn + +@deftypefn {} ColumnVector solve (void) +@deftypefnx {} ColumnVector solve (const ColumnVector &@var{x}) +@end deftypefn + +@deftypefn {} ColumnVector solve (int &@var{info}) +@deftypefnx{} ColumnVector solve (const ColumnVector &@var{x}, int &@var{info}) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/ode.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,77 @@ +@node Ordinary Differential Equations, Differential Algebraic Equations, Nonlinear Equations, Top +@chapter Ordinary Differential Equations +@cindex ODE + +@deftypefn {} {}ODE_options (void) +@deftypefnx {} {}ODE_options (const ODE_options &@var{opt}) +@end deftypefn + +@deftypefn {} ODE_options& {operator =} (const ODE_options &@var{opt}) +@end deftypefn + +@deftypefn {} void init (void) +@end deftypefn + +@deftypefn {} void copy (const ODE_options &@var{opt}) +@end deftypefn + +@deftypefn {} void set_default_options (void) +@end deftypefn + +@deftypefn {} void set_absolute_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_initial_step_size (double @var{val}) +@end deftypefn + +@deftypefn {} void set_maximum_step_size (double @var{val}) +@end deftypefn + +@deftypefn {} void set_minimum_step_size (double @var{val}) +@end deftypefn + +@deftypefn {} void set_relative_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} double absolute_tolerance (void) +@deftypefnx {} double initial_step_size (void) +@deftypefnx {} double maximum_step_size (void) +@deftypefnx {} double minimum_step_size (void) +@deftypefnx {} double relative_tolerance (void) +@end deftypefn + +@deftypefn {} {}ODE (void) +@deftypefnx {} {}ODE (int @var{n}) +@deftypefnx {} {}ODE (const ColumnVector &@var{state}, double @var{time}, const ODEFunc &@var{f}) +@end deftypefn + +@deftypefn {} {virtual int} size (void) const +@end deftypefn + +@deftypefn {} {virtual ColumnVector} state (void) const +@end deftypefn + +@deftypefn {} {virtual double} time (void) const +@end deftypefn + +@deftypefn {} {virtual void} force_restart (void) +@end deftypefn + +@deftypefn {} {virtual void} initialize (const ColumnVector &@var{x}, double @var{t}) +@end deftypefn + +@deftypefn {} {virtual void} set_stop_time (double @var{t}) +@end deftypefn + +@deftypefn {} {virtual void} clear_stop_time (void) +@end deftypefn + +@deftypefn {} {virtual ColumnVector} integrate (double @var{t}) +@end deftypefn + +@deftypefn {} void integrate (int @var{nsteps}, double @var{tstep}, ostream &@var{s}) +@end deftypefn + +@deftypefn {} Matrix integrate (const ColumnVector &@var{tout}) +@deftypefnx {} Matrix integrate (const ColumnVector &@var{tout}, const ColumnVector &@var{tcrit}) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/optim.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,351 @@ +@node Objective Functions, Quadrature, Nonlinear Functions, Top +@chapter Objective Functions +@cindex objective functions + +@deftypefn {} {}Objective (void) +@deftypefnx {} {}Objective (const @var{objective_fcn}) +@deftypefnx {} {}Objective (const @var{objective_fcn}, const @var{gradient_fcn}) +@deftypefnx {} {}Objective (const Objective &@var{a}) +@end deftypefn + +@deftypefn {} Objective& {operator =} (const Objective &@var{a}) +@end deftypefn + +@deftypefn {} objective_fcn objective_function (void) const; +@end deftypefn + +@deftypefn {} Objective& set_objective_function (const @var{objective_fcn}) +@end deftypefn + +@deftypefn {} gradient_fcn gradient_function (void) const; +@end deftypefn + +@deftypefn {} Objective& set_gradient_function (const @var{gradient_fcn}) +@end deftypefn + +@c ------------------------------------------------------------------------ + +@node Bounds, Linear Constraints, Objective Functions +@chapter Bounds +@cindex bounds + +@deftypefn {} {}Bounds (void) +@deftypefnx {} {}Bounds (int @var{n}) +@deftypefnx {} {}Bounds (const ColumnVector @var{lb}, const ColumnVector @var{ub}) +@deftypefnx {} {}Bounds (const Bounds &@var{a}) +@end deftypefn + +@deftypefn {} Bounds& {operator =} (const Bounds &@var{a}) +@end deftypefn + +@deftypefn {} Bounds& resize (int @var{n}) +@end deftypefn + +@deftypefn {} double lower_bound (int @var{index}) const; +@deftypefnx {} double upper_bound (int @var{index}) const; +@end deftypefn + +@deftypefn {} ColumnVector lower_bounds (void) const; +@deftypefnx {} ColumnVector upper_bounds (void) const; +@end deftypefn + +@deftypefn {} int size (void) const; +@end deftypefn + +@deftypefn {} Bounds& set_bound (int @var{index}, double @var{low}, double @var{high}) +@end deftypefn + +@deftypefn {} Bounds& set_bounds (double @var{low}, double @var{high}) +@deftypefnx {} Bounds& set_bounds (const ColumnVector @var{lb}, const ColumnVector @var{ub}) +@end deftypefn + +@deftypefn {} Bounds& set_lower_bound (int @var{index}, double @var{low}) +@deftypefnx {} Bounds& set_upper_bound (int @var{index}, double @var{high}) +@end deftypefn + +@deftypefn {} Bounds& set_lower_bounds (double @var{low}) +@deftypefnx {} Bounds& set_upper_bounds (double @var{high}) +@end deftypefn + +@deftypefn {} Bounds& set_lower_bounds (const ColumnVector @var{lb}) +@deftypefnx {} Bounds& set_upper_bounds (const ColumnVector @var{ub}) +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const Bounds &@var{b}) +@end deftypefn + +@c ------------------------------------------------------------------------ + +@node Linear Constraints, Nonlinear Constraints, Bounds +@chapter Linear Constraints +@cindex linear Constraints + +@deftypefn {} {}LinConst (void) +@deftypefnx {} {}LinConst (int @var{nclin}, int @var{nx}) +@deftypefnx {} {}LinConst (int @var{nclin_eq}, int @var{nclin_ineq}, int @var{nx}) +@deftypefnx {} {}LinConst (const ColumnVector &@var{lb}, const Matrix &@var{A}, const ColumnVector &@var{ub}) +@deftypefnx {} {}LinConst (const Matrix &@var{A_eq}, const ColumnVector &@var{b_eq}, const Matrix &@var{A_ineq}, const ColumnVector &@var{b_ineq}) +@deftypefnx {} {}LinConst (const LinConst &@var{a}) +@end deftypefn + +@deftypefn {} LinConst& {operator =} (const LinConst &@var{a}) +@end deftypefn + +@deftypefn {} LinConst& resize (int @var{nclin}, int @var{n}) +@end deftypefn + +@deftypefn {} Matrix constraint_matrix (void) const; +@end deftypefn + +@deftypefn {} LinConst& set_constraint_matrix (const Matrix &@var{A}) +@end deftypefn + +@deftypefn {} Matrix eq_constraint_matrix (void) const; +@deftypefnx {} Matrix ineq_constraint_matrix (void) const; +@end deftypefn + +@deftypefn {} ColumnVector eq_constraint_vector (void) const; +@deftypefnx {} ColumnVector ineq_constraint_vector (void) const; +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const LinConst &@var{b}) +@end deftypefn + +@c ------------------------------------------------------------------------ + +@node Nonlinear Constraints, Quadratic Programming, Linear Constraints +@chapter Nonlinear Constraints +@cindex nonlinear Constraints + +@deftypefn {} {}NLConst (void) +@deftypefnx {} {}NLConst (int @var{n}) +@deftypefnx {} {}NLConst (const ColumnVector @var{lb}, const NLFunc @var{f}, const ColumnVector @var{ub}) +@deftypefnx {} {}NLConst (const NLConst &@var{a}) +@end deftypefn + +@deftypefn {} NLConst& {operator =} (const NLConst &@var{a}) +@end deftypefn + +@node Quadratic Programming, Nonlinear Programming, Nonlinear Constraints +@chapter Quadratic Programming +@cindex QP +@cindex quadratic programming + +@deftypefn {} {}QP (void) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}, const Bounds &@var{b}) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}, const LinConst &@var{lc}) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}, const Bounds &@var{b}) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}, const LinConst &@var{lc}) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}, const Bounds &@var{b}, const LinConst &@var{lc}) +@deftypefnx {} {}QP (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}, const Bounds &@var{b}, const LinConst &@var{lc}) +@end deftypefn + +@deftypefn {} {virtual ColumnVector} minimize (void) +@deftypefnx {} {virtual ColumnVector} minimize (double &@var{objf}) +@deftypefnx {} {virtual ColumnVector} minimize (double &@var{objf}, int &@var{inform}) +@deftypefnx {} {virtual ColumnVector} minimize (double &@var{objf}, int &@var{inform}, ColumnVector &@var{lambda}) = 0; +@end deftypefn + +@deftypefn {} {virtual ColumnVector} minimize (const ColumnVector &@var{x}) +@deftypefnx {} {virtual ColumnVector} minimize (const ColumnVector &@var{x}, double &@var{objf}) +@deftypefnx {} {virtual ColumnVector} minimize (const ColumnVector &@var{x}, double &@var{objf}, int &@var{inform}) +@deftypefnx {} {virtual ColumnVector} minimize (const ColumnVector &@var{x}, double &@var{objf}, int &@var{inform}, ColumnVector &@var{lambda}) +@end deftypefn + +@deftypefn {} {}QPSOL_options (void) +@deftypefnx {} {}QPSOL_options (const QPSOL_options &@var{opt}) +@end deftypefn + +@deftypefn {} QPSOL_options& {operator =} (const QPSOL_options &@var{opt}) +@end deftypefn + +@deftypefn {} void init (void) +@end deftypefn + +@deftypefn {} void copy (const QPSOL_options &@var{opt}) +@end deftypefn + +@deftypefn {} void set_default_options (void) +@end deftypefn + +@deftypefn {} void set_feasibility_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_infinite_bound (double @var{val}) +@end deftypefn + +@deftypefn {} void set_iteration_limit (int @var{val}) +@end deftypefn + +@deftypefn {} void set_print_level (int @var{val}) +@end deftypefn + +@deftypefn {} double feasibility_tolerance (void) +@deftypefnx {} double infinite_bound (void) +@deftypefnx {} int iteration_limit (void) +@deftypefnx {} int print_level (void) +@end deftypefn + +@deftypefn {} {}QPSOL (void) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}, const Bounds &@var{b}) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}, const LinConst &@var{lc}) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}, const Bounds &@var{b}) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}, const LinConst &@var{lc}) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}, const Bounds &@var{b}, const LinConst &@var{lc}) +@deftypefnx {} {}QPSOL (const ColumnVector &@var{x}, const Matrix &@var{H}, const ColumnVector &@var{c}, const Bounds &@var{b}, const LinConst &@var{lc}) +@deftypefnx {} {}QPSOL (const QPSOL &@var{a}) +@end deftypefn + +@deftypefn {} QPSOL& {operator =} (const QPSOL &@var{a}) +@end deftypefn + +@deftypefn {} ColumnVector minimize (double &@var{objf}, int &@var{inform}, ColumnVector &@var{lambda}) +@end deftypefn + +@c ------------------------------------------------------------------------ + +@node Nonlinear Programming, , Quadratic Programming +@chapter Nonlinear Programming +@cindex NLP +@cindex nonlinear programming + +@deftypefn {} {}NLP (void) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}, const LinConst &@var{lc}) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}, const LinConst &@var{lc}, const NLConst &@var{nlc}) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}, const LinConst &@var{lc}) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}, const LinConst &@var{lc}, const NLConst &@var{nlc}) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}, const NLConst &@var{nlc}) +@deftypefnx {} {}NLP (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}, const NLConst &@var{nlc}) +@end deftypefn + +@deftypefn {} NLP& {operator =} (const NLP &@var{a}) +@end deftypefn + +@deftypefn {} int size (void) const +@end deftypefn + +@deftypefn {} {}NPSOL_options (void) +@deftypefnx {} {}NPSOL_options (const NPSOL_options &@var{opt}) +@end deftypefn + +@deftypefn {} NPSOL_options& {operator =} (const NPSOL_options &@var{opt}) +@end deftypefn + +@deftypefn {} void init (void) +@deftypefnx {} void copy (const NPSOL_options &@var{opt}) +@end deftypefn + +@deftypefn {} void set_default_options (void) +@end deftypefn + +@deftypefn {} void set_central_difference_interval (double @var{val}) +@end deftypefn + +@deftypefn {} void set_crash_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_difference_interval (double @var{val}) +@end deftypefn + +@deftypefn {} void set_function_precision (double @var{val}) +@end deftypefn + +@deftypefn {} void set_infinite_bound (double @var{val}) +@end deftypefn + +@deftypefn {} void set_infinite_step (double @var{val}) +@end deftypefn + +@deftypefn {} void set_linear_feasibility_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_linesearch_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_nonlinear_feasibility_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_optimality_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_derivative_level (int @var{val}) +@end deftypefn + +@deftypefn {} void set_major_iteration_limit (int @var{val}) +@end deftypefn + +@deftypefn {} void set_minor_iteration_limit (int @var{val}) +@end deftypefn + +@deftypefn {} void set_major_print_level (int @var{val}) +@end deftypefn + +@deftypefn {} void set_minor_print_level (int @var{val}) +@end deftypefn + +@deftypefn {} void set_start_objective_check (int @var{val}) +@end deftypefn + +@deftypefn {} void set_start_constraint_check (int @var{val}) +@end deftypefn + +@deftypefn {} void set_stop_objective_check (int @var{val}) +@end deftypefn + +@deftypefn {} void set_stop_constraint_check (int @var{val}) +@end deftypefn + +@deftypefn {} void set_verify_level (int @var{val}) +@end deftypefn + +@deftypefn {} double central_difference_interval (void) const +@deftypefnx {} double crash_tolerance (void) const +@deftypefnx {} double difference_interval (void) const +@deftypefnx {} double function_precision (void) const +@deftypefnx {} double infinite_bound (void) const +@deftypefnx {} double infinite_step (void) const +@deftypefnx {} double linear_feasibility_tolerance (void) const +@deftypefnx {} double linesearch_tolerance (void) const +@deftypefnx {} double nonlinear_feasibility_tolerance (void) const +@deftypefnx {} double optimality_tolerance (void) const +@deftypefnx {} int derivative_level (void) const +@deftypefnx {} int major_iteration_limit (void) const +@deftypefnx {} int minor_iteration_limit (void) const +@deftypefnx {} int major_print_level (void) const +@deftypefnx {} int minor_print_level (void) const +@deftypefnx {} int start_objective_check (void) const +@deftypefnx {} int start_constraint_check (void) const +@deftypefnx {} int stop_objective_check (void) const +@deftypefnx {} int stop_constraint_check (void) const +@deftypefnx {} int verify_level (void) const +@end deftypefn + +@deftypefn {} {}NPSOL (void) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}, const LinConst &@var{lc}) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}, const LinConst &@var{lc}, const NLConst &@var{nlc}) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}, const LinConst &@var{lc}) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}, const LinConst &@var{lc}, const NLConst &@var{nlc}) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}, const NLConst &@var{nlc}) +@deftypefnx {} {}NPSOL (const ColumnVector &@var{x}, const Objective &@var{phi}, const Bounds &@var{b}, const NLConst &@var{nlc}) +@deftypefnx {} {}NPSOL (const NPSOL &@var{a}) +@end deftypefn + +@deftypefn {} ColumnVector minimize (void) +@deftypefnx {} ColumnVector minimize (double &@var{objf}) +@deftypefnx {} ColumnVector minimize (double &@var{objf}, int &@var{inform}) +@deftypefnx {} ColumnVector minimize (double &@var{objf}, int &@var{inform}, ColumnVector &@var{lambda}) +@end deftypefn + +@deftypefn {} ColumnVector minimize (const ColumnVector &@var{x}) +@deftypefnx {} ColumnVector minimize (const ColumnVector &@var{x}, double &@var{objf}) +@deftypefnx {} ColumnVector minimize (const ColumnVector &@var{x}, double &@var{objf}, int &@var{inform}) +@deftypefnx {} ColumnVector minimize (const ColumnVector &@var{x}, double &@var{objf}, int &@var{inform}, ColumnVector &@var{lambda}) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/preface.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,15 @@ +@node Acknowledgements, Copying, Top, Top +@chapter Acknowledgements +@cindex acknowledgements + +@menu +* Contributors:: People who contributed to developing of Octave. +@end menu + +@node Contributors, , Acknowledgements, Acknowledgements +@unnumberedsec Contributors to Octave +@cindex contributors + +In addition to John W. Eaton, several people have written parts +of liboctave. (This has been removed because it is the same as what is +in the Octave manual.)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/quad.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,119 @@ +@node Quadrature, Ordinary Differential Equations, Objective Functions, Top +@chapter Quadrature +@cindex quadrature +@cindex numerical integration +@cindex integration + +@deftypefn {} {}Quad (integrand_fcn @var{fcn}) +@deftypefnx {} {}Quad (integrand_fcn @var{fcn}, double @var{abs}, double @var{rel}) +@end deftypefn + +@deftypefn {} {virtual double} integrate (void) +@deftypefnx {} {virtual double} integrate (int &@var{ier}) +@deftypefnx {} {virtual double} integrate (int &@var{ier}, int &@var{neval}) +@deftypefnx {} {virtual double} integrate (int &@var{ier}, int &@var{neval}, double &@var{abserr}) = 0 +@end deftypefn + +@deftypefn {} Quad_options (void) +@deftypefnx {} Quad_options (const Quad_options &@var{opt}) +@end deftypefn + +@deftypefn {} Quad_options& {operator =} (const Quad_options &@var{opt}) +@end deftypefn + +@deftypefn {} void init (void) +@end deftypefn + +@deftypefn {} void copy (const Quad_options &@var{opt}) +@end deftypefn + +@deftypefn {} void set_default_options (void) +@end deftypefn + +@deftypefn {} void set_absolute_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} void set_relative_tolerance (double @var{val}) +@end deftypefn + +@deftypefn {} double absolute_tolerance (void) +@deftypefnx {} double relative_tolerance (void) +@end deftypefn + +@deftypefn {} {}DefQuad (integrand_fcn @var{fcn}) +@deftypefnx {} {}DefQuad (integrand_fcn @var{fcn}, double @var{ll}, double @var{ul}) +@deftypefnx {} {}DefQuad (integrand_fcn @var{fcn}, double @var{ll}, double @var{ul}, double @var{abs}, double @var{rel}) +@deftypefnx {} {}DefQuad (integrand_fcn @var{fcn}, double @var{ll}, double @var{ul}, const ColumnVector &@var{sing}) +@deftypefnx {} {}DefQuad (integrand_fcn @var{fcn}, const ColumnVector &@var{sing}, double @var{abs}, double @var{rel}) +@deftypefnx {} {}DefQuad (integrand_fcn @var{fcn}, const ColumnVector &@var{sing}) +@deftypefnx {} {}DefQuad (integrand_fcn @var{fcn}, double @var{ll}, double @var{ul}, const ColumnVector &@var{sing}, double @var{abs}, double @var{rel}) +@end deftypefn + +@deftypefn {} {}IndefQuad (integrand_fcn @var{fcn}) +@deftypefnx {} {}IndefQuad (integrand_fcn @var{fcn}, double @var{b}, IntegralType @var{t}) +@deftypefnx {} {}IndefQuad (integrand_fcn @var{fcn}, double @var{b}, IntegralType @var{t}, double @var{abs}, double @var{rel}) +@deftypefnx {} {}IndefQuad (integrand_fcn @var{fcn}, double @var{abs}, double @var{rel}) +@end deftypefn + +@node Collocation Weights, , Quadrature +@chapter Collocation Weights +@cindex orthogonal collocation +@cindex collocation weights + +@deftypefn {} {}CollocWt (void) +@deftypefnx {} {}CollocWt (int @var{n}, int @var{inc_l}, int @var{inc_r}) +@deftypefnx {} {}CollocWt (int @var{n}, int @var{inc_l}, int @var{inc_r}, double @var{l}, double @var{r}) +@deftypefnx {} {}CollocWt (int @var{n}, double @var{a}, double @var{b}, int @var{inc_l}, int @var{inc_r}) +@deftypefnx {} {}CollocWt (int @var{n}, int @var{inc_l}, int @var{inc_r}, double @var{l}, double @var{r}) +@deftypefnx {} {}CollocWt (const CollocWt&) +@end deftypefn + +@deftypefn {} CollocWt& {operator =} (const CollocWt&) +@end deftypefn + +@deftypefn {} CollocWt& resize (int @var{ncol}) +@end deftypefn + +@deftypefn {} CollocWt& add_left (void) +@deftypefnx {} CollocWt& add_right (void) +@end deftypefn + +@deftypefn {} CollocWt& delete_left (void) +@deftypefnx {} CollocWt& delete_right (void) +@end deftypefn + +@deftypefn {} CollocWt& set_left (double @var{val}) +@deftypefnx {} CollocWt& set_right (double @var{val}) +@end deftypefn + +@deftypefn {} CollocWt& set_alpha (double @var{val}) +@deftypefnx {} CollocWt& set_beta (double @var{val}) +@end deftypefn + +@deftypefn {} int ncol (void) const +@end deftypefn + +@deftypefn {} int left_included (void) const +@deftypefnx {} int right_included (void) const +@end deftypefn + +@deftypefn {} double left (void) const +@deftypefnx {} double right (void) const +@deftypefnx {} double width (void) const +@end deftypefn + +@deftypefn {} double alpha (void) const +@deftypefnx {} double beta (void) const +@end deftypefn + +@deftypefn {} ColumnVector roots (void) +@deftypefnx {} ColumnVector quad (void) +@deftypefnx {} ColumnVector quad_weights (void) +@end deftypefn + +@deftypefn {} Matrix first (void) +@deftypefnx {} Matrix second (void) +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const CollocWt &@var{c}) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/liboctave/range.texi Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,36 @@ +@node Ranges, Nonlinear Functions, Matrix Factorizations, Top +@chapter Ranges +@cindex ranges + +@deftypefn {} {}Range (void) +@deftypefnx {} {}Range (const Range &@var{r}) +@deftypefnx {} {}Range (double @var{b}, double @var{l}) +@deftypefnx {} {}Range (double @var{b}, double @var{l}, double @var{i}) +@end deftypefn + +@deftypefn {} double base (void) const +@deftypefnx {} double limit (void) const +@deftypefnx {} double inc (void) const +@end deftypefn + +@deftypefn {} void set_base (double @var{b}) +@deftypefnx {} void set_limit (double @var{l}) +@deftypefnx {} void set_inc (double @var{i}) +@end deftypefn + +@deftypefn {} int nelem (void) const +@end deftypefn + +@deftypefn {} double min (void) const +@deftypefnx {} double max (void) const +@end deftypefn + +@deftypefn {} void sort (void) +@end deftypefn + +@deftypefn {} {ostream&} {operator <<} (ostream &@var{os}, const Range &@var{r}) +@deftypefnx {} {istream&} {operator >>} (istream &@var{is}, Range &@var{r}) +@end deftypefn + +@deftypefn {} void print_range (void) +@end deftypefn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/refcard/refcard-a4.tex Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,6 @@ +% refcard-a4.tex +% +% Make a reference card that will fit on A4 paper. + +\def\refcardsize{a4} +\input refcard.tex
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/refcard/refcard-legal.tex Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,6 @@ +% refcard-legal.tex +% +% Make a reference card that will fit on US legal paper. + +\def\refcardsize{legal} +\input refcard.tex
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/refcard/refcard-letter.tex Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,7 @@ +% refcard-letter.tex +% +% Make a reference card that will fit on US letter paper +% (8-1/2 by 11 inches). + +\def\refcardsize{letter} +\input refcard.tex
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/refcard/refcard.tex Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,952 @@ +% refcard.tex +% +% This file is TeX source for a reference card describing Octave. +% +% John W. Eaton +% jwe@che.utexas.edu +% Department of Chemical Engineering +% The University of Texas at Austin +% +% Heavily modified by jwe from the source for the gdb reference card, +% which was orignally written by Roland Pesch <pesch@cygnus.com>. +% +% Copyright (C) 1991, 1992 Free Software Foundation, Inc. +% Permission is granted to make and distribute verbatim copies of +% this reference provided the copyright notices and permission notices +% are preserved on all copies. +% +% TeX markup is a programming language; accordingly this file is source +% for a program to generate a reference. +% +% This program is free software; you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 2, or (at your option) +% any later version. +% +% This program is distributed in the hope that it will be useful, but +% WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% General Public License for more details. +% +% You can find a copy of the GNU General Public License in the GDB +% manual; or write to the Free Software Foundation, Inc., +% 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +% +% You only have to set the total width and height of the paper, the +% horizontal and vertical margin space measured from *paper edge* +% and the interline and interspec spacing. +% In order to support a new papersize, you have to fiddle with the +% latter four dimensions. Just try out a few values. +% All other values will be computed at process time so it should be +% quite easy to support different paper sizes - only four values to +% guess :-) +% +% To find the configuration places, just search for the string +% "User configuration". +% +% -- Andreas Vogel (av@ssw.de) +% +% NOTE ON INTENTIONAL OMISSIONS: This reference card includes many +% Octave commands, but due to space constraints there are some things +% I chose to omit. In general, not all synonyms for commands are +% covered, nor all variations of a command. + +\def\octaveversion{1.1.1} +\def\refcardedition{1.1} + +% ------------------ +% multicolumn format +% ------------------ + +% Declarations (these must come first) + +\newdimen\totalwidth +\newdimen\totalheight +\newdimen\hmargin +\newdimen\vmargin +\newdimen\secskip +\newdimen\lskip +\newdimen\barwidth +\newdimen\barheight +\newdimen\intersecwidth + +\newcount\columnsperpage + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% % +% CONFIGURATION % +% % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% There are currently 8 total columns, so some of these options will +% not create a single page reference card. + +% Choose a paper size. Default is US letter size. + +\def\refcardafoursize{a4} % 3 columns, A4 paper (1 in = 254 mm) +\def\refcardlegalsize{legal} % 4 columns, US legal paper (8.5 x 14in) +\def\refcardlettersize{letter} % 3 columns, US letter paper (8.5 x 14in) + +\ifx\refcardsize\refcardafoursize + \columnsperpage=3 % total number of columns to typeset + \totalwidth=297mm % total width of paper + \totalheight=210mm % total height of paper + \hmargin=9mm % horizontal margin width + \vmargin=7mm % vertical margin width + \secskip=3mm % space between refcard secs + \lskip=0.4mm % extra skip between \sec entries +\else + \ifx\refcardsize\refcardlegalsize + \columnsperpage=4 % total number of columns to typeset + \totalwidth=14in % total width of paper + \totalheight=8.5in % total height of paper + \hmargin=0.20in % horizontal margin width + \vmargin=0.25in % vertical margin width + \secskip=0.75pc % space between refcard secs + \lskip=2pt % extra skip between \sec entries + \else + \columnsperpage=3 % total number of columns to typeset + \totalwidth=11in % total width of paper + \totalheight=8.5in % total height of paper + \hmargin=0.25in % horizontal margin width + \vmargin=0.25in % vertical margin width + \secskip=0.75pc % space between refcard secs + \lskip=2pt % extra skip between \sec entries + \fi +\fi + +% Change according to personal taste, not papersize dependent. + +\barwidth=.1pt % width of the cropmark bar +\barheight=2pt % height of the cropmark bar +\intersecwidth=0.5em % width between \itmwid and \dfnwid + +% Uncomment only one of the following definitions for folding guides. + +% No printed folding guide: + +%\def\vdecor{\hskip\hmargin plus1fil +% \hskip\barwidth plus1fil +% \hskip\hmargin plus1fil} + +% Solid line folding guide: + +%\def\vdecor{\hskip\hmargin plus1fil% +% \vrule width \barwidth% +% \hskip\hmargin plus1fil} + +% For small marks near top and bottom as folding guide: + +\def\vdecor{\hskip\hmargin plus1fil% + \vbox to \vsize{\hbox to \barwidth{\vrule height\barheight width\barwidth}% + \vfill + \hbox to \barwidth{\vrule height\barheight width\barwidth}}% + \hskip\hmargin plus1fil} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% % +% END CONFIGURATION % +% % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% values to be computed based on above definitions. +% nothing to configure + +\newdimen\fullhsize % width of area without margins +\newdimen\itmwid % width of item column +\newdimen\dfnwid % width of definition column +\newdimen\idnwid % width of indented text +\newdimen\temp % only for temporary use + +% an alternate section format, used in some cases to make text fit better. + +\newdimen\altitmwid % width of item column in altsec +\newdimen\altdfnwid % width of definition column in altsec + +% Subtract hmargin for left and right sides of paper from full width. +% +% fullhsize = totalwidth - (2 * hmargin) + +\fullhsize=\totalwidth +\temp=\hmargin +\multiply \temp by 2 +\advance \fullhsize by -\temp + +% intercolumn space is composed of hmargin barwidth hmargin so that we +% get the same amount of space on either side of the (optional) rule +% between columns. For N columns, we need to subtract this amount of +% space N-1 times. Divide by the number of columns to get the final +% value of \hsize that we use to typeset columns. + +% hsize = (fullhsize - (ncols-1)*barwidth - 2*(ncols-1)*hmargin) / ncols + +\newcount\tmpcnt +\tmpcnt\columnsperpage +\advance \tmpcnt by -1 + +\hsize=\fullhsize + +\temp=\barwidth +\multiply \temp by \tmpcnt +\advance \hsize by -\temp + +\multiply \tmpcnt by 2 + +\temp=\hmargin +\multiply \temp by \tmpcnt +\advance \hsize by -\temp + +\divide \hsize by \columnsperpage + +% Vertical size is easy -- same amount of space above and below. +% +% vsize = totalheight - (2 * vmargin) + +\vsize=\totalheight +\temp=\vmargin +\multiply \temp by 2 +\advance \vsize by -\temp + +% adjust the offsets so the margins are measured *from paper edge* + +\hoffset=-1in \advance \hoffset by \hmargin +\voffset=-1in \advance \voffset by \vmargin + +% Width of items in a section. + +% itmwid = (hsize - intersecwidth) * 1/3 +% dfnwid = (hsize - intersecwidth) * 2/3 + +% width of the item + +\temp=\hsize +\advance \temp by -\intersecwidth +\divide \temp by 3 +\itmwid=\temp + +% width of the corresponding definition + +\dfnwid=\hsize +\advance \dfnwid by -\itmwid + +% indentation for sub items, etc. + +\temp=\hsize \advance\temp by -1em +\idnwid=\temp + +% Width of items in an alt section. + +\altitmwid=\itmwid \advance \altitmwid by 0.35in +\altdfnwid=\dfnwid \advance \altdfnwid by -0.35in + +% Output macros. +% +% Strategy: +% +% * set each column in a box +% * append new columns in a global `holding' box, inserting +% intercolumn decorations as necessary. +% * when we fill a page, dump the saved box and the latest column, +% separated by the intercolumn decoration. + +\newbox\holdbox +\newcount\colno +\colno=0 + +\output={\relax + \global\advance\colno by 1 + \ifnum\colno=1 + \global\setbox\holdbox=\columnbox + \else + \ifnum\colno=\columnsperpage + \shipout\hbox to \fullhsize{\box\holdbox\vdecor\columnbox} + \advancepageno + \global\colno=0 + \else + \global\setbox\holdbox=\vbox{\hbox{\box\holdbox\vdecor\columnbox}} + \fi + \fi} + +\def\columnbox{\leftline{\pagebody}} + +\def\bye{\par\vfill + \supereject + \if R\lcr \null\vfill\eject \fi + \end} + +% ----- +% Fonts +% ----- + +\font\bbf=cmbx10 +\font\vbbf=cmbx12 +\font\smrm=cmr6 +\font\brm=cmr10 +\font\rm=cmr7 +\font\it=cmti7 +\font\tt=cmtt8 + +% We can afford to allow some slop + +\hfuzz=1pt +\vfuzz=1pt +\hyphenpenalty=5000 +\tolerance=2000 +\raggedright +\raggedbottom +\normalbaselineskip=9pt +\baselineskip=9pt + +\parindent=0pt +\parskip=0pt +\footline={\vbox to0pt{\hss}} + +\def\ctl#1{{\tt C-#1}} +\def\opt#1{{\brm[{\rm #1}]}} +\def\xtra#1{\noalign{\smallskip{\tt#1}}} + +% A normal section + +\long\def\sec#1;#2\endsec{\vskip \secskip + \halign{% +% +% column 1 (of halign): +% + \vtop{\hsize=\itmwid\tt ##\par\vskip \lskip }\hfil +% +% column 2 (of halign): +% + &\vtop{% + \hsize=\dfnwid + \hangafter=1 + \hangindent=\intersecwidth + \rm ##\par\vskip \lskip}\cr +% +% Tail of \long\def fills in halign body with \sec args: +% + \noalign{{\bbf #1}% + \vskip \lskip} + #2}} + +\long\def\widesec#1;#2\endsec{\vskip \secskip + \halign{% +% +% column 1 (of halign): +% + \vbox{\tt + ##\par\vskip \lskip }\cr +% +% Tail of \long\def fills in halign body with \sec args: +% + \noalign{{\bbf #1}\vskip 3\lskip} + #2}} + +% an alternate section format, used in some cases to make text fit better. + +\long\def\altsec#1;#2\endsec{\vskip \secskip + \halign{% +% +% column 1 (of halign): +% + \vtop{\hsize=\altitmwid\tt + ##\par\vskip \lskip}\hfil +% +% column 2 (of halign): +% + &\vtop{% + \hsize=\altdfnwid + \hangafter=1 + \hangindent=\intersecwidth + \rm ##\par\vskip \lskip}\cr +% +% Tail of \long\def fills in halign body with \sec args: +% + \noalign{{\bbf #1}\vskip \lskip} + #2}} + +% ------------------------------------- +% The actual text of the reference card +% ------------------------------------- + +{\vbbf Octave Quick Reference}\hfil{\smrm Octave Version \octaveversion}\qquad + +\sec Starting Octave; +octave&start interactive Octave session\cr +octave {\it file}&run Octave on commands in {\it file}\cr +octave --help&describe command line options\cr +\endsec + +\sec Stopping Octave; +quit {\rm or} exit&exit Octave\cr +INTERRUPT&({\it e.g.} \ctl{c}) terminate current command and return to + top-level prompt\cr +\endsec + +\sec Getting Help; +help&list all commands and built-in variables\cr +help {\it command}&briefly describe {\it command}\cr +help -i&use Info to browse Octave manual\cr +help -i {\it command}&search for {\it command\/} in Octave manual\cr +\endsec + +\sec Motion in Info; +SPC {\rm or} C-v&scroll forward one screenful\cr +DEL {\rm or} M-v&scroll backward one screenful\cr +C-l&redraw the display\cr +\endsec + +\sec Node Selection in Info; +n&select the next node\cr +p&select the previous node\cr +u&select the `up' node\cr +t&select the `top' node\cr +d&select the directory node\cr +<&select the first node in the current file\cr +>&select the last node in the current file\cr +% ]&move forward through the node structure\cr +% [&move backward through the nodes\cr +g&reads the name of a node and selects it\cr +C-x k&kills the current node\cr +\endsec + +\sec Searching in Info; +s&search for a string\cr +C-s&search forward incrementally\cr +C-r&search backward incrementally\cr +i&search index \& go to corresponding node\cr +,&go to next match from last `i' command\cr +\endsec + +\sec Command-Line Cursor Motion; +C-b&move back one character\cr +C-f&move forward one character\cr +C-a&move the the start of the line\cr +C-e&move to the end of the line\cr +M-f&move forward a word\cr +M-b&move backward a word\cr +C-l&clear screen, reprinting current line at top\cr +\endsec + +\sec Inserting or Changing Text; +M-TAB&insert a tab character\cr +DEL&delete character to the left of the cursor\cr +C-d&delete character under the cursor\cr +C-v&add the next character verbatim\cr +C-t&transpose characters at the point\cr +M-t&transpose words at the point\cr +% M-u&uppercase the current word\cr +% M-l&lowercase the current word\cr +% M-c&capitalize the current word\cr +\endsec + +\vfill +\line{\smrm \opt{ } surround optional arguments + \hfill ... show one or more arguments} +\vskip0.25\baselineskip +\centerline{\smrm Copyright 1996, John W. Eaton\qquad Permissions on back} +\eject + +\sec Killing and Yanking; +C-k&kill to the end of the line\cr +C-y&yank the most recently killed text\cr +M-d&kill to the end of the current word\cr +M-DEL&kill the word behind the cursor\cr +M-y&rotate the kill ring and yank the new top\cr +\endsec + +\sec Command Completion and History; +TAB&complete a command or variable name\cr +M-?&list possible completions\cr + +RET&enter the current line \cr +C-p&move `up' through the history list\cr +C-n&move `down' through the history list\cr +M-<&move to the first line in the history\cr +M->&move to the last line in the history\cr +C-r&search backward in the history list\cr +C-s&search forward in the history list\cr + +history \opt{{-q}} \opt{{\it N\/}}&list {\it N\/} previous history lines, + omitting history numbers if {\tt -q}\cr +history -w \opt{{\it file}}&write history to {\it file\/} ({\tt + \char'0176/.octave\_hist} if no {\it file\/} argument)\cr +history -r \opt{{\it file}}&read history from {\it file\/} ({\tt + \char'0176/.octave\_hist} if no {\it file\/} argument)\cr + +edit\_history {\it lines}&edit and then run previous + commands from the history list\cr +run\_history {\it lines}&run previous commands from the + history list\cr +\quad\opt{{\it beg\/}} \opt{{\it end\/}}&Specify the first and last + history commands to edit or run.\cr +\omit\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + If {\it beg}\/ is greater than {\it end}, + reverse the list of commands before editing. If {\it end\/} is + omitted, select commands from {\it beg\/} to the end of the history + list. If both arguments are omitted, edit the previous item in the + history list.}\span\cr +\endsec + +\sec Shell Commands; +cd {\it dir}&change working directory to {\it dir}\cr +pwd&print working directory\cr +ls \opt{{\it options}}&print directory listing\cr +getenv ({\it string})&return value of named environment variable\cr +system ({\it cmd})&execute arbitrary shell command string\cr +\endsec + +\sec Matrices; +\omit\vbox{\rm\vskip0.25ex + Square brackets delimit literal matrices. Commas separate elements + on the same row. Semicolons separate rows. Commas may be replaced + by spaces, and semicolons may be replaced by one or more newlines. + Elements of a matrix may be arbitrary expressions, provided that + all the dimensions agree.\vskip0.75ex}\span\cr +[ {\it x}, {\it y}, ... ]&enter a row vector\cr +[ {\it x}; {\it y}; ... ]&enter a column vector\cr +[ {\it w}, {\it x}; {\it y}, {\it z} ]&enter a 2$\times$2 matrix\cr +\endsec + +\sec Ranges; +{\it base} : {\it limit}\cr +{\it base} : {\it incr} : {\it limit}\cr +\omit\hfill\vbox{\hsize=\idnwid\rm\vskip0.75ex + Specify a range of values beginning with {\it base\/} with no elements + greater than {\it limit}. If it is omitted, the default value of + {\it incr\/} is 1. Negative increments are permitted.}\span\cr +\endsec + +\vfill\eject + +\sec Strings and Common Escape Sequences; +\omit\vbox{\rm\vskip0.5ex + A {\it string constant\/} consists of a sequence of characters + enclosed in either double-quote or single-quote marks.\vskip0.75ex}\span\cr +\char'134\char'134&a literal backslash\cr +\char'134 "&a literal double-quote character\cr +\char'134 '&a literal single-quote character\cr +\char'134 n&newline, ASCII code 10\cr +\char'134 t&horizontal tab, ASCII code 9\cr +\endsec + +\sec Index Expressions; +{\it var} ({\it idx})&select elements of a vector\cr +{\it var} ({\it idx1}, {\it idx2})&select elements of a matrix\cr + +\quad {\it scalar}&select row (column) corresponding to {\it scalar}\cr +\quad {\it vector}&select rows (columns) corresponding to the elements + of {\it vector}\cr +\quad {\it range}&select rows (columns) corresponding to the elements + of {\it range}\cr +\quad :&select all rows (columns)\cr +\endsec + +\sec Global Variables; +global {\it var1} ...&Declare variables global.\cr +\omit\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + Global variables may be accessed inside the body of a function + without having to be passed in the function parameter list provided + they are also declared global within the function.}\span\cr +\endsec + +\sec Selected Built-in Variables; +EDITOR&editor to use with {\tt edit\_history}\cr +Inf, NaN&IEEE infinity, NaN\cr +LOADPATH&path to search for function files\cr +PAGER&program to use to paginate output\cr +ans&last result not explicitly assigned\cr +eps&machine precision\cr +pi&$\pi$\cr +realmax&maximum representable value\cr +realmin&minimum representable value\cr +\endsec +\vskip -\secskip +\vskip -2\lskip +\altsec \null; +automatic\_replot&automatically redraw plots\cr +do\_fortran\_indexing&Fortran-style indexing of matrices\cr +implicit\_str\_to\_num\_ok&allow strings to become numbers\cr +output\_max\_field\_width&maximum numeric field width\cr +output\_precision&min significant figures displayed\cr +page\_screen\_output&control whether output is paged\cr +prefer\_column\_vectors&create column vectors by default\cr +resize\_on\_range\_error&automatic resizing of matrices\cr +save\_precision&digits stored by {\tt save} command\cr +silent\_functions&suppress output from functions\cr +warn\_divide\_by\_zero&suppress divide by zero errors\cr +\endsec +\vskip -\secskip +\vskip -2\lskip +\widesec \null; +commas\_in\_literal\_matrix\vskip\lskip\cr +\omit\hfill\vbox{\hsize=\idnwid\rm + control handling of spaces in matrices\vskip3\lskip}\cr +ignore\_function\_time\_stamp\cr +\omit\hfill\vbox{\hsize=\idnwid\rm + ignore changes in function files during session\vskip3\lskip}\cr +ok\_to\_lose\_imaginary\_part\cr +\omit\hfill\vbox{\hsize=\idnwid\rm + allow complex to real conversion\vskip3\lskip}\cr +prefer\_zero\_one\_indexing\cr +\omit\hfill\vbox{\hsize=\idnwid\rm + if ambiguous, prefer 0-1 style indexing\vskip3\lskip}\cr +\endsec + +\vfill\eject + +\sec Arithmetic and Increment Operators; +{\it x} + {\it y}&addition\cr +{\it x} - {\it y}&subtraction\cr +{\it x} * {\it y}&matrix multiplication\cr +{\it x} .* {\it y}&element by element multiplication\cr +{\it x} / {\it y}&right division, conceptually equivalent to + {\tt (inverse~(y')~*~x')'}\cr +{\it x} ./ {\it y}&element by element right division\cr +{\it x} \char'134{} {\it y}&left division, conceptually equivalent to + {\tt inverse~(x)~*~y}\cr +{\it x} .\char'134{} {\it y}&element by element left division\cr +{\it x} \char'136{} {\it y}&power operator\cr +{\it x} .\char'136{} {\it y}&element by element power operator\cr +- {\it x}&negation\cr ++ {\it x}&unary plus (a no-op)\cr +{\it x} '&complex conjugate transpose\cr +{\it x} .'&transpose\cr +++ {\it x}\quad{\rm(}-- {\it x}{\rm)}&increment (decrement) {\it x}, + return {\it new\/} value\cr +{\it x} ++\quad{\rm(}{\it x} --{\rm)}&increment (decrement) {\it x}, + return {\it old\/} value\cr +\endsec + +\sec Assignment Expressions; +{\it var} = {\it expr}&assign expression to variable\cr +{\it var} ({\it idx}) = {\it expr}&assign expression to indexed variable\cr +\endsec + +\sec Comparison and Boolean Operators; +\omit \vbox{\rm\vskip0.75ex + These operators work on an element-by-element basis. Both arguments + are always evaluated.\vskip0.75ex}\span\cr +{\it x} < {\it y}&true if {\it x\/} is less than {\it y}\cr +{\it x} <= {\it y}&true if {\it x\/} is less than or equal to {\it y}\cr +{\it x} == {\it y}&true if {\it x\/} is greater than {\it y}\cr +{\it x} >= {\it y}&true if {\it x\/} is greater than or equal to {\it y}\cr +{\it x} > {\it y}&true if {\it x\/} is equal to {\it y}\cr +{\it x} != {\it y}&true if {\it x\/} is not equal to {\it y}\cr +{\it x} \& {\it y}&true if both {\it x\/} and {\it y\/} are true\cr +{\it x} | {\it y}&true if at least one of {\it x\/} or {\it y\/} is true\cr +! {\it bool}&true {\it bool\/} is false\cr +\endsec + +\sec Short-circuit Boolean Operators; +\omit \vbox{\rm\vskip0.75ex + Operators evaluate left-to-right, expecting scalar operands. + Operands are only evaluated if necessary, stopping once overall + truth value can be determined. Operands are converted to scalars by + applying the {\tt all} function.\vskip0.75ex}\span\cr +{\it x} \&\& {\it y}&true if both {\it x\/} and {\it y\/} are true\cr +{\it x} || {\it y}&true if at least one of {\it x\/} or {\it y\/} is true\cr +\endsec + +\sec Operator Precedence; +\omit \vbox{\rm\vskip0.5ex + Here is a table of the operators in Octave, in order of increasing + precedence.\vskip0.75ex}\span\cr +;\ \ ,&statement separators\cr +=&assignment, groups left to right\cr +||\ \ \&\&&logical ``or'' and ``and''\cr +|\ \ \&&element-wise ``or'' and ``and''\cr +< <= == >= > !=&relational operators\cr +:&colon\cr ++\ \ -&addition and subtraction\cr +* / \char'134\ \ .*\ \ ./\ \ .\char'134&multiplication and division\cr +'\ \ .'&transpose\cr ++\ \ -\ \ ++\ \ --\ \ !&unary minus, increment, logical ``not''\cr +\char'136\ \ .\char'136&exponentiation\cr +\endsec + +\vfill\eject + +\widesec Statements; +for {\it identifier} = {\it expr} {\it stmt-list} endfor\cr +\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + Execute {\it stmt-list} once for each column of {\it expr}. The + variable {\it identifier} is set to the value of the current column + during each iteration.}\cr\cr +while ({\it condition}) {\it stmt-list} endwhile\cr +\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + Execute {\it stmt-list} while {\it condition} is true.}\cr\cr +\hbox{\vtop{\hsize=\itmwid\tt break} + \vtop{\hsize=\dfnwid\rm exit innermost loop}}\cr +\hbox{\vtop{\hsize=\itmwid\tt continue} + \vtop{\hsize=\dfnwid\rm go to beginning of innermost loop}}\cr +\hbox{\vtop{\hsize=\itmwid\tt return} + \vtop{\hsize=\dfnwid\rm return to calling function}}\cr\cr +if ({\it condition}) {\it if-body} \opt{{\tt else} {\it else-body}} endif\cr +\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + Execute {\it if-body} if {\it condition} is true, otherwise execute + {\it else-body}.}\cr +if ({\it condition}) {\it if-body} \opt{{\tt elseif} ({\it condition}) + {\it elseif-body}} endif\cr +\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + Execute {\it if-body} if {\it condition} is true, otherwise execute + the {\it elseif-body} corresponding to the first {\tt elseif} + condition that is true, otherwise execute {\it else-body}.}\cr +\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + Any number of {\tt elseif} clauses may appear in an {\tt if} + statement.}\cr\cr +unwind\_protect {\it body} unwind\_protect\_cleanup {\it cleanup} end\cr +\hfill\vbox{\hsize=\idnwid\rm\vskip0.25ex + Execute {\it body}. Execute {\it cleanup} no matter how control +exits {\it body}.}\cr +\endsec + +\widesec Defining Functions; +function \opt{{\it ret-list}} {\it function-name} + \opt{\hskip0.2em({\it arg-list})\hskip0.2em}\cr +\quad{\it function-body}\cr +endfunction\cr\cr +{\rm {\it ret-list\/} may be a single identifier or a comma-separated + list of identifiers delimited by square-brackets.\vskip0.75ex}\cr +{\rm {\it arg-list\/} is a comma-separated list of identifiers and may + be empty.}\cr +\endsec + +\sec Basic Matrix Manipulations; +rows ({\it a})&return number of rows of {\it a}\cr +columns ({\it a})&return number of columns of {\it a}\cr +all ({\it a})&check if all elements of {\it a\/} nonzero\cr +any ({\it a})&check if any elements of {\it a\/} nonzero\cr +find ({\it a})&return indices of nonzero elements\cr +sort ({\it a})&order elements in each column of {\it a}\cr +sum ({\it a})&sum elements in columns of {\it a}\cr +prod ({\it a})&product of elements in columns of {\it a}\cr +min ({\it args})&find minimum values\cr +max ({\it args})&find maximum values\cr +rem ({\it x}, {\it y})&find remainder of {\it x}/{\it y}\cr +reshape ({\it a}, {\it m}, {\it n})&reformat {\it a} to be {\it m} by + {\it n}\cr\cr +diag ({\it v}, {\it k})&create diagonal matrices\cr +linspace ({\it b}, {\it l}, {\it n})&create vector of linearly-spaced + elements\cr +logspace ({\it b}, {\it l}, {\it n})&create vector of log-spaced + elements\cr +eye ({\it n}, {\it m})&create {\it n\/} by {\it m\/} identity matrix\cr +ones ({\it n}, {\it m})&create {\it n\/} by {\it m\/} matrix of ones\cr +zeros ({\it n}, {\it m})&create {\it n\/} by {\it m\/} matrix of zeros\cr +rand ({\it n}, {\it m})&create {\it n\/} by {\it m\/} matrix of random + values\cr +\endsec + +\vfill\eject + +% sin({\it a}) cos({\it a}) tan({\it a})&trigonometric functions\cr +% asin({\it a}) acos({\it a}) atan({\it a})&inverse trigonometric functions\cr +% sinh({\it a}) cosh({\it a}) tanh({\it a})&hyperbolic trig functions\cr +% asinh({\it a}) acosh({\it a}) atanh({\it a})&inverse hyperbolic trig +% functions\cr\cr + +\sec Linear Algebra; +chol ({\it a})&Cholesky factorization\cr +det ({\it a})&compute the determinant of a matrix\cr +eig ({\it a})&eigenvalues and eigenvectors\cr +expm ({\it a})&compute the exponential of a matrix\cr +hess ({\it a})&compute Hessenberg decomposition\cr +inverse ({\it a})&invert a square matrix\cr +norm ({\it a}, {\it p})&compute the {\it p}-norm of a matrix\cr +pinv ({\it a})&compute pseudoinverse of {\it a}\cr +qr ({\it a})&compute the QR factorization of a matrix\cr +rank ({\it a})&matrix rank\cr +schur ({\it a})&Schur decomposition of a matrix\cr +svd ({\it a})&singular value decomposition\cr +syl ({\it a}, {\it b}, {\it c})&solve the Sylvester equation\cr +\endsec + +\sec Equations, ODEs, DAEs, Quadrature; +*fsolve&solve nonlinear algebraic equations\cr +*lsode&integrate nonlinear ODEs\cr +*dassl&integrate nonlinear DAEs\cr +*quad&integrate nonlinear functions\cr\cr +perror ({\it nm}, {\it code})&for functions that return numeric + codes, print error message for named function and given error + code\cr\cr +\omit \vbox{\rm + {\tt *} See the on-line or printed manual for the complete list of + arguments for these functions.}\span\cr +\endsec + +\sec Signal Processing; +fft ({\it a})&Fast Fourier Transform using FFTPACK\cr +ifft ({\it a})&inverse FFT using FFTPACK\cr +freqz ({\it args})&FIR filter frequency response\cr +sinc ({\it x})&returns {\tt sin ($\pi$ x)/($\pi$ x)}\cr +\endsec + +\altsec Image Processing; +colormap ({\it map})&set the current colormap\cr +gray2ind ({\it i}, {\it n})&convert gray scale to Octave image\cr +image ({\it img}, {\it zoom})&display an Octave image matrix\cr +imagesc ({\it img}, {\it zoom})&display scaled matrix as image\cr +imshow ({\it img}, {\it map})&display Octave image\cr +imshow ({\it i}, {\it n})&display gray scale image\cr +imshow ({\it r}, {\it g}, {\it b})&display RGB image\cr +ind2gray ({\it img}, {\it map})&convert Octave image to gray scale\cr +ind2rgb ({\it img}, {\it map})&convert indexed image to RGB\cr +loadimage ({\it file})&load an image file\cr +rgb2ind ({\it r}, {\it g}, {\it b})&convert RGB to Octave image\cr +\omit\tt saveimage ({\it file}, {\it img}, {\it fmt}, {\it map})\quad\rm +save a matrix to {\it file}\span\cr +\endsec + +\altsec Sets; +create\_set ({\it a}, {\it b})&create row vector of unique values\cr +complement ({\it a}, {\it b})&elements of {\it b} not in {\it a}\cr +intersection ({\it a}, {\it b})&intersection of sets {\it a} and {\it b}\cr +union ({\it a}, {\it b})&union of sets {\it a} and {\it b}\cr +\endsec + +\altsec Strings; +strcmp ({\it s}, {\it t})&compare strings\cr +strcat ({\it s}, {\it t}, ...)&concatenate strings\cr +\endsec + +\vfill\eject + +\altsec C-style Input and Output; +fopen ({\it name}, {\it mode})&open file {\it name}\cr +fclose ({\it file})&close {\it file}\cr +printf ({\it fmt}, ...)&formatted output to {\tt stdout}\cr +fprintf ({\it file}, {\it fmt}, ...)&formatted output to {\it file}\cr +sprintf ({\it fmt}, ...)&formatted output to string\cr +scanf ({\it fmt})&formatted input from {\tt stdin}\cr +fscanf ({\it file}, {\it fmt})&formatted input from {\it file}\cr +sscanf ({\it str}, {\it fmt})&formatted input from {\it string}\cr +fgets ({\it file}, {\it len})&read {\it len\/} characters from {\it file\/}\cr +fflush ({\it file})&flush pending output to {\it file}\cr +ftell ({\it file})&return file pointer position\cr +frewind ({\it file})&move file pointer to beginning\cr +freport&print a info for open files\cr +fread ({\it file}, {\it size}, {\it prec})&read binary data files\cr +fwrite ({\it file}, {\it size}, {\it prec})&write binary data files\cr +feof ({\it file})&determine if pointer is at EOF\cr +\omit \vbox{\rm\vskip0.75ex + A file may be referenced either by name or by the number returned + from {\tt fopen}. Three files are preconnected when Octave starts: + {\tt stdin}, {\tt stdout}, and {\tt stderr}.\vskip0.75ex}\span\cr +\endsec + +\sec Other Input and Output functions; +save {\it file} {\it var} ...&save variables in {\it file}\cr +load {\it file}&load variables from {\it file}\cr +disp ({\it var})&display value of {\it var} to screen\cr +\endsec + +\sec Miscellaneous Functions; +eval ({\it str})&evaluate {\it str} as a command\cr +feval ({\it str}, ...)&evaluate function named by {\it str}, + passing remaining args to called function\cr\cr +error ({\it message})&print message and return to top level\cr\cr +clear {\it pattern}&clear variables matching pattern\cr +exist ({\it str})&check existence of variable or function\cr +who&list current variables\cr +\endsec + +\sec Polynomials; +compan ({\it p})&companion matrix\cr +conv ({\it a}, {\it b})&convolution\cr +deconv ({\it a}, {\it b})&deconvolve two vectors\cr +poly ({\it a})&create polynomial from a matrix\cr +polyderiv ({\it p})&derivative of polynomial\cr +polyreduce ({\it p})&integral of polynomial\cr +polyval ({\it p}, {\it x})&value of polynomial at {\it x}\cr +polyvalm ({\it p}, {\it x})&value of polynomial at {\it x}\cr +roots ({\it p})&polynomial roots\cr +residue ({\it a}, {\it b})&partial fraction expansion of +ratio {\it a}/{\it b}\cr +\endsec + +\sec Statistics; +corrcoef ({\it x}, {\it y})&correlation coefficient\cr +cov ({\it x}, {\it y})&covariance\cr +mean ({\it a})&mean value\cr +median ({\it a})&median value\cr +std ({\it a})&standard deviation\cr +var ({\it a})&variance\cr +\endsec + +\vfill\eject + +\sec Basic Plotting; +\omit \vbox{\tt +gplot \opt{{\it ranges}} {\it expr} \opt{{\it using}} + \opt{{\it title}} \opt{{\it style}}\hfill{\rm 2D plotting} + \par\vskip \lskip}\span\cr +\omit \vbox{\tt +gsplot \opt{{\it ranges}} {\it expr} \opt{{\it using}} + \opt{{\it title}} \opt{{\it style}}\hfill{\rm 3D plotting} + \par\vskip \lskip}\span\cr +\quad{\it ranges}&specify data ranges\cr +\quad{\it expr}&expression to plot\cr +\quad{\it using}&specify columns to plot\cr +\quad{\it title}&specify line title for legend\cr +\quad{\it style}&specify line style\cr +\omit \vbox{\rm\vskip0.85ex + If {\it ranges\/} are supplied, they must come before the expression + to plot. The {\it using\/}, {\it title\/}, and {\it style\/} + options may appear in any order after {\it expr\/}. Multiple + expressions may be plotted with a single command by separating them + with commas.\vskip1ex}\span\cr +set {\it options}&set plotting options\cr +show {\it options}&show plotting options\cr +replot&redisplay current plot\cr +closeplot&close stream to {\tt gnuplot} process\cr +purge\_tmp\_files&clean up temporary plotting files\cr +automatic\_replot&built-in variable\cr +\endsec + +\sec Other Plotting Functions; +plot ({\it args})&2D plot with linear axes\cr +semilogx ({\it args})&2D plot with logarithmic x-axis\cr +semilogy ({\it args})&2D plot with logarithmic y-axis\cr +loglog ({\it args})&2D plot with logarithmic axes\cr +bar ({\it args})&plot bar charts\cr +stairs ({\it x}, {\it y})&plot stairsteps\cr +hist ({\it y}, {\it x})&plot histograms\cr\cr +title ({\it string})&set plot title\cr\cr +axis ({\it limits})&set axis ranges\cr +xlabel ({\it string})&set x-axis label\cr +ylabel ({\it string})&set y-axis label\cr +grid \opt{on$|$off}&set grid state\cr +hold \opt{on$|$off}&set hold state\cr +ishold&return 1 if hold is on, 0 otherwise\cr\cr +mesh ({\it x}, {\it y}, {\it z})&plot 3D surface\cr +meshdom ({\it x}, {\it y})&create mesh coordinate matrices\cr +\endsec + +\vskip 0pt plus 2fill +\hrule width \hsize +\par\vskip10pt +{\smrm\parskip=6pt +Edition \refcardedition for Octave Version \octaveversion. Copyright +1996, John W. Eaton +(jwe@che.utexas.edu). The author assumes no responsibility for any +errors on this card. + +This card may be freely distributed under the terms of the GNU +General Public License. + +\TeX{} Macros for this card by Roland Pesch (pesch@cygnus.com), +originally for the GDB reference card + +Octave itself is free software; you are welcome to distribute copies of +it under the terms of the GNU General Public License. There is +absolutely no warranty for Octave. +} + +\end + +% For AUCTeX: +% +% Local Variables: +% mode: tex +% TeX-master: t +% End:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/texinfo.tex Fri Jul 19 02:26:23 1996 +0000 @@ -0,0 +1,4412 @@ +%% TeX macros to handle texinfo files + +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 1994 Free Software Foundation, Inc. + +%This texinfo.tex file is free software; you can redistribute it and/or +%modify it under the terms of the GNU General Public License as +%published by the Free Software Foundation; either version 2, or (at +%your option) any later version. + +%This texinfo.tex file is distributed in the hope that it will be +%useful, but WITHOUT ANY WARRANTY; without even the implied warranty +%of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +%General Public License for more details. + +%You should have received a copy of the GNU General Public License +%along with this texinfo.tex file; see the file COPYING. If not, write +%to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, +%USA. + + +%In other words, you are welcome to use, share and improve this program. +%You are forbidden to forbid anyone else to use, share and improve +%what you give them. Help stamp out software-hoarding! + + +% Send bug reports to bug-texinfo@prep.ai.mit.edu. +% Please include a *precise* test case in each bug report. + + +% Make it possible to create a .fmt file just by loading this file: +% if the underlying format is not loaded, start by loading it now. +% Added by gildea November 1993. +\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi + +% This automatically updates the version number based on RCS. +\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2+gildea patch}} +\deftexinfoversion$Revision: 1.1 $ +\message{Loading texinfo package [Version \texinfoversion]:} + +% If in a .fmt file, print the version number +% and turn on active characters that we couldn't do earlier because +% they might have appeared in the input file name. +\everyjob{\message{[Texinfo version \texinfoversion]}\message{} + \catcode`+=\active\catcode`\_=\active} + +% Save some parts of plain tex whose names we will redefine. + +\let\ptextilde=\~ +\let\ptexlbrace=\{ +\let\ptexrbrace=\} +\let\ptexdots=\dots +\let\ptexdot=\. +\let\ptexstar=\* +\let\ptexend=\end +\let\ptexbullet=\bullet +\let\ptexb=\b +\let\ptexc=\c +\let\ptexi=\i +\let\ptext=\t +\let\ptexl=\l +\let\ptexL=\L + +% Be sure we're in horizontal mode when doing a tie, since we make space +% equivalent to this in @example-like environments. Otherwise, a space +% at the beginning of a line will start with \penalty -- and +% since \penalty is valid in vertical mode, we'd end up putting the +% penalty on the vertical list instead of in the new paragraph. +{\catcode`@ = 11 + \gdef\tie{\leavevmode\penalty\@M\ } +} +\let\~ = \tie % And make it available as @~. + +\message{Basics,} +\chardef\other=12 + +% If this character appears in an error message or help string, it +% starts a new line in the output. +\newlinechar = `^^J + +% Set up fixed words for English. +\ifx\putwordChapter\undefined{\gdef\putwordChapter{Chapter}}\fi% +\def\putwordInfo{Info}% +\ifx\putwordSee\undefined{\gdef\putwordSee{See}}\fi% +\ifx\putwordsee\undefined{\gdef\putwordsee{see}}\fi% +\ifx\putwordfile\undefined{\gdef\putwordfile{file}}\fi% +\ifx\putwordpage\undefined{\gdef\putwordpage{page}}\fi% +\ifx\putwordsection\undefined{\gdef\putwordsection{section}}\fi% +\ifx\putwordSection\undefined{\gdef\putwordSection{Section}}\fi% +\ifx\putwordTableofContents\undefined{\gdef\putwordTableofContents{Table of Contents}}\fi% +\ifx\putwordShortContents\undefined{\gdef\putwordShortContents{Short Contents}}\fi% +\ifx\putwordAppendix\undefined{\gdef\putwordAppendix{Appendix}}\fi% + +% Ignore a token. +% +\def\gobble#1{} + +\hyphenation{ap-pen-dix} +\hyphenation{mini-buf-fer mini-buf-fers} +\hyphenation{eshell} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen \bindingoffset \bindingoffset=0pt +\newdimen \normaloffset \normaloffset=\hoffset +\newdimen\pagewidth \newdimen\pageheight +\pagewidth=\hsize \pageheight=\vsize + +% Sometimes it is convenient to have everything in the transcript file +% and nothing on the terminal. We don't just call \tracingall here, +% since that produces some useless output on the terminal. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{\tracingcommands2 \tracingstats2 + \tracingpages1 \tracingoutput1 \tracinglostchars1 + \tracingmacros2 \tracingparagraphs1 \tracingrestores1 + \showboxbreadth\maxdimen\showboxdepth\maxdimen +}% + +%---------------------Begin change----------------------- +% +%%%% For @cropmarks command. +% Dimensions to add cropmarks at corners Added by P. A. MacKay, 12 Nov. 1986 +% +\newdimen\cornerlong \newdimen\cornerthick +\newdimen \topandbottommargin +\newdimen \outerhsize \newdimen \outervsize +\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks +\outerhsize=7in +%\outervsize=9.5in +% Alternative @smallbook page size is 9.25in +\outervsize=9.25in +\topandbottommargin=.75in +% +%---------------------End change----------------------- + +% \onepageout takes a vbox as an argument. Note that \pagecontents +% does insertions itself, but you have to call it yourself. +\chardef\PAGE=255 \output={\onepageout{\pagecontents\PAGE}} +\def\onepageout#1{\hoffset=\normaloffset +\ifodd\pageno \advance\hoffset by \bindingoffset +\else \advance\hoffset by -\bindingoffset\fi +{\escapechar=`\\\relax % makes sure backslash is used in output files. +\shipout\vbox{{\let\hsize=\pagewidth \makeheadline} \pagebody{#1}% +{\let\hsize=\pagewidth \makefootline}}}% +\advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi} + +%%%% For @cropmarks command %%%% + +% Here is a modification of the main output routine for Near East Publications +% This provides right-angle cropmarks at all four corners. +% The contents of the page are centerlined into the cropmarks, +% and any desired binding offset is added as an \hskip on either +% site of the centerlined box. (P. A. MacKay, 12 November, 1986) +% +\def\croppageout#1{\hoffset=0pt % make sure this doesn't mess things up +{\escapechar=`\\\relax % makes sure backslash is used in output files. + \shipout + \vbox to \outervsize{\hsize=\outerhsize + \vbox{\line{\ewtop\hfill\ewtop}} + \nointerlineskip + \line{\vbox{\moveleft\cornerthick\nstop} + \hfill + \vbox{\moveright\cornerthick\nstop}} + \vskip \topandbottommargin + \centerline{\ifodd\pageno\hskip\bindingoffset\fi + \vbox{ + {\let\hsize=\pagewidth \makeheadline} + \pagebody{#1} + {\let\hsize=\pagewidth \makefootline}} + \ifodd\pageno\else\hskip\bindingoffset\fi} + \vskip \topandbottommargin plus1fill minus1fill + \boxmaxdepth\cornerthick + \line{\vbox{\moveleft\cornerthick\nsbot} + \hfill + \vbox{\moveright\cornerthick\nsbot}} + \nointerlineskip + \vbox{\line{\ewbot\hfill\ewbot}} + }} + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi} +% +% Do @cropmarks to get crop marks +\def\cropmarks{\let\onepageout=\croppageout } + +\newinsert\margin \dimen\margin=\maxdimen + +\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} +{\catcode`\@ =11 +\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi +% marginal hacks, juha@viisa.uucp (Juha Takala) +\ifvoid\margin\else % marginal info is present + \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi +\dimen@=\dp#1 \unvbox#1 +\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi +\ifr@ggedbottom \kern-\dimen@ \vfil \fi} +} + +% +% Here are the rules for the cropmarks. Note that they are +% offset so that the space between them is truly \outerhsize or \outervsize +% (P. A. MacKay, 12 November, 1986) +% +\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} +\def\nstop{\vbox + {\hrule height\cornerthick depth\cornerlong width\cornerthick}} +\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} +\def\nsbot{\vbox + {\hrule height\cornerlong depth\cornerthick width\cornerthick}} + +% Parse an argument, then pass it to #1. The argument is the rest of +% the input line (except we remove a trailing comment). #1 should be a +% macro which expects an ordinary undelimited TeX argument. +% +\def\parsearg#1{% + \let\next = #1% + \begingroup + \obeylines + \futurelet\temp\parseargx +} + +% If the next token is an obeyed space (from an @example environment or +% the like), remove it and recurse. Otherwise, we're done. +\def\parseargx{% + % \obeyedspace is defined far below, after the definition of \sepspaces. + \ifx\obeyedspace\temp + \expandafter\parseargdiscardspace + \else + \expandafter\parseargline + \fi +} + +% Remove a single space (as the delimiter token to the macro call). +{\obeyspaces % + \gdef\parseargdiscardspace {\futurelet\temp\parseargx}} + +{\obeylines % + \gdef\parseargline#1^^M{% + \endgroup % End of the group started in \parsearg. + % + % First remove any @c comment, then any @comment. + % Result of each macro is put in \toks0. + \argremovec #1\c\relax % + \expandafter\argremovecomment \the\toks0 \comment\relax % + % + % Call the caller's macro, saved as \next in \parsearg. + \expandafter\next\expandafter{\the\toks0}% + }% +} + +% Since all \c{,omment} does is throw away the argument, we can let TeX +% do that for us. The \relax here is matched by the \relax in the call +% in \parseargline; it could be more or less anything, its purpose is +% just to delimit the argument to the \c. +\def\argremovec#1\c#2\relax{\toks0 = {#1}} +\def\argremovecomment#1\comment#2\relax{\toks0 = {#1}} + +% \argremovec{,omment} might leave us with trailing spaces, though; e.g., +% @end itemize @c foo +% will have two active spaces as part of the argument with the +% `itemize'. Here we remove all active spaces from #1, and assign the +% result to \toks0. +% +% This loses if there are any *other* active characters besides spaces +% in the argument -- _ ^ +, for example -- since they get expanded. +% Fortunately, Texinfo does not define any such commands. (If it ever +% does, the catcode of the characters in questionwill have to be changed +% here.) But this means we cannot call \removeactivespaces as part of +% \argremovec{,omment}, since @c uses \parsearg, and thus the argument +% that \parsearg gets might well have any character at all in it. +% +\def\removeactivespaces#1{% + \begingroup + \ignoreactivespaces + \edef\temp{#1}% + \global\toks0 = \expandafter{\temp}% + \endgroup +} + +% Change the active space to expand to nothing. +% +\begingroup + \obeyspaces + \gdef\ignoreactivespaces{\obeyspaces\let =\empty} +\endgroup + + +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +%% These are used to keep @begin/@end levels from running away +%% Call \inENV within environments (after a \begingroup) +\newif\ifENV \ENVfalse \def\inENV{\ifENV\relax\else\ENVtrue\fi} +\def\ENVcheck{% +\ifENV\errmessage{Still within an environment. Type Return to continue.} +\endgroup\fi} % This is not perfect, but it should reduce lossage + +% @begin foo is the same as @foo, for now. +\newhelp\EMsimple{Type <Return> to continue.} + +\outer\def\begin{\parsearg\beginxxx} + +\def\beginxxx #1{% +\expandafter\ifx\csname #1\endcsname\relax +{\errhelp=\EMsimple \errmessage{Undefined command @begin #1}}\else +\csname #1\endcsname\fi} + +% @end foo executes the definition of \Efoo. +% +\def\end{\parsearg\endxxx} +\def\endxxx #1{% + \removeactivespaces{#1}% + \edef\endthing{\the\toks0}% + % + \expandafter\ifx\csname E\endthing\endcsname\relax + \expandafter\ifx\csname \endthing\endcsname\relax + % There's no \foo, i.e., no ``environment'' foo. + \errhelp = \EMsimple + \errmessage{Undefined command `@end \endthing'}% + \else + \unmatchedenderror\endthing + \fi + \else + % Everything's ok; the right environment has been started. + \csname E\endthing\endcsname + \fi +} + +% There is an environment #1, but it hasn't been started. Give an error. +% +\def\unmatchedenderror#1{% + \errhelp = \EMsimple + \errmessage{This `@end #1' doesn't have a matching `@#1'}% +} + +% Define the control sequence \E#1 to give an unmatched @end error. +% +\def\defineunmatchedend#1{% + \expandafter\def\csname E#1\endcsname{\unmatchedenderror{#1}}% +} + + +% Single-spacing is done by various environments (specifically, in +% \nonfillstart and \quotations). +\newskip\singlespaceskip \singlespaceskip = 12.5pt +\def\singlespace{% + % Why was this kern here? It messes up equalizing space above and below + % environments. --karl, 6may93 + %{\advance \baselineskip by -\singlespaceskip + %\kern \baselineskip}% + \setleading \singlespaceskip +} + +%% Simple single-character @ commands + +% @@ prints an @ +% Kludge this until the fonts are right (grr). +\def\@{{\tt \char '100}} + +% This is turned off because it was never documented +% and you can use @w{...} around a quote to suppress ligatures. +%% Define @` and @' to be the same as ` and ' +%% but suppressing ligatures. +%\def\`{{`}} +%\def\'{{'}} + +% Used to generate quoted braces. + +\def\mylbrace {{\tt \char '173}} +\def\myrbrace {{\tt \char '175}} +\let\{=\mylbrace +\let\}=\myrbrace + +% @: forces normal size whitespace following. +\def\:{\spacefactor=1000 } + +% @* forces a line break. +\def\*{\hfil\break\hbox{}\ignorespaces} + +% @. is an end-of-sentence period. +\def\.{.\spacefactor=3000 } + +% @enddots{} is an end-of-sentence ellipsis. +\gdef\enddots{$\mathinner{\ldotp\ldotp\ldotp\ldotp}$\spacefactor=3000} + +% @! is an end-of-sentence bang. +\gdef\!{!\spacefactor=3000 } + +% @? is an end-of-sentence query. +\gdef\?{?\spacefactor=3000 } + +% @w prevents a word break. Without the \leavevmode, @w at the +% beginning of a paragraph, when TeX is still in vertical mode, would +% produce a whole line of output instead of starting the paragraph. +\def\w#1{\leavevmode\hbox{#1}} + +% @group ... @end group forces ... to be all on one page, by enclosing +% it in a TeX vbox. We use \vtop instead of \vbox to construct the box +% to keep its height that of a normal line. According to the rules for +% \topskip (p.114 of the TeXbook), the glue inserted is +% max (\topskip - \ht (first item), 0). If that height is large, +% therefore, no glue is inserted, and the space between the headline and +% the text is small, which looks bad. +% +\def\group{\begingroup + \ifnum\catcode13=\active \else + \errhelp = \groupinvalidhelp + \errmessage{@group invalid in context where filling is enabled}% + \fi + % + % The \vtop we start below produces a box with normal height and large + % depth; thus, TeX puts \baselineskip glue before it, and (when the + % next line of text is done) \lineskip glue after it. (See p.82 of + % the TeXbook.) Thus, space below is not quite equal to space + % above. But it's pretty close. + \def\Egroup{% + \egroup % End the \vtop. + \endgroup % End the \group. + }% + % + \vtop\bgroup + % We have to put a strut on the last line in case the @group is in + % the midst of an example, rather than completely enclosing it. + % Otherwise, the interline space between the last line of the group + % and the first line afterwards is too small. But we can't put the + % strut in \Egroup, since there it would be on a line by itself. + % Hence this just inserts a strut at the beginning of each line. + \everypar = {\strut}% + % + % Since we have a strut on every line, we don't need any of TeX's + % normal interline spacing. + \offinterlineskip + % + % OK, but now we have to do something about blank + % lines in the input in @example-like environments, which normally + % just turn into \lisppar, which will insert no space now that we've + % turned off the interline space. Simplest is to make them be an + % empty paragraph. + \ifx\par\lisppar + \edef\par{\leavevmode \par}% + % + % Reset ^^M's definition to new definition of \par. + \obeylines + \fi + % + % Do @comment since we are called inside an environment such as + % @example, where each end-of-line in the input causes an + % end-of-line in the output. We don't want the end-of-line after + % the `@group' to put extra space in the output. Since @group + % should appear on a line by itself (according to the Texinfo + % manual), we don't worry about eating any user text. + \comment +} +% +% TeX puts in an \escapechar (i.e., `@') at the beginning of the help +% message, so this ends up printing `@group can only ...'. +% +\newhelp\groupinvalidhelp{% +group can only be used in environments such as @example,^^J% +where each line of input produces a line of output.} + +% @need space-in-mils +% forces a page break if there is not space-in-mils remaining. + +\newdimen\mil \mil=0.001in + +\def\need{\parsearg\needx} + +% Old definition--didn't work. +%\def\needx #1{\par % +%% This method tries to make TeX break the page naturally +%% if the depth of the box does not fit. +%{\baselineskip=0pt% +%\vtop to #1\mil{\vfil}\kern -#1\mil\penalty 10000 +%\prevdepth=-1000pt +%}} + +\def\needx#1{% + % Go into vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % Don't add any leading before our big empty box, but allow a page + % break, since the best break might be right here. + \allowbreak + \nointerlineskip + \vtop to #1\mil{\vfil}% + % + % TeX does not even consider page breaks if a penalty added to the + % main vertical list is 10000 or more. But in order to see if the + % empty box we just added fits on the page, we must make it consider + % page breaks. On the other hand, we don't want to actually break the + % page after the empty box. So we use a penalty of 9999. + % + % There is an extremely small chance that TeX will actually break the + % page at this \penalty, if there are no other feasible breakpoints in + % sight. (If the user is using lots of big @group commands, which + % almost-but-not-quite fill up a page, TeX will have a hard time doing + % good page breaking, for example.) However, I could not construct an + % example where a page broke at this \penalty; if it happens in a real + % document, then we can reconsider our strategy. + \penalty9999 + % + % Back up by the size of the box, whether we did a page break or not. + \kern -#1\mil + % + % Do not allow a page break right after this kern. + \nobreak +} + +% @br forces paragraph break + +\let\br = \par + +% @dots{} output some dots + +\def\dots{$\ldots$} + +% @page forces the start of a new page + +\def\page{\par\vfill\supereject} + +% @exdent text.... +% outputs text on separate line in roman font, starting at standard page margin + +% This records the amount of indent in the innermost environment. +% That's how much \exdent should take out. +\newskip\exdentamount + +% This defn is used inside fill environments such as @defun. +\def\exdent{\parsearg\exdentyyy} +\def\exdentyyy #1{{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}} + +% This defn is used inside nofill environments such as @example. +\def\nofillexdent{\parsearg\nofillexdentyyy} +\def\nofillexdentyyy #1{{\advance \leftskip by -\exdentamount +\leftline{\hskip\leftskip{\rm#1}}}} + +%\hbox{{\rm#1}}\hfil\break}} + +% @include file insert text of that file as input. + +\def\include{\parsearg\includezzz} +%Use \input\thisfile to avoid blank after \input, which may be an active +%char (in which case the blank would become the \input argument). +%The grouping keeps the value of \thisfile correct even when @include +%is nested. +\def\includezzz #1{\begingroup +\def\thisfile{#1}\input\thisfile +\endgroup} + +\def\thisfile{} + +% @center line outputs that line, centered + +\def\center{\parsearg\centerzzz} +\def\centerzzz #1{{\advance\hsize by -\leftskip +\advance\hsize by -\rightskip +\centerline{#1}}} + +% @sp n outputs n lines of vertical space + +\def\sp{\parsearg\spxxx} +\def\spxxx #1{\par \vskip #1\baselineskip} + +% @comment ...line which is ignored... +% @c is the same as @comment +% @ignore ... @end ignore is another way to write a comment + +\def\comment{\catcode 64=\other \catcode 123=\other \catcode 125=\other% +\parsearg \commentxxx} + +\def\commentxxx #1{\catcode 64=0 \catcode 123=1 \catcode 125=2 } + +\let\c=\comment + +% Prevent errors for section commands. +% Used in @ignore and in failing conditionals. +\def\ignoresections{% +\let\chapter=\relax +\let\unnumbered=\relax +\let\top=\relax +\let\unnumberedsec=\relax +\let\unnumberedsection=\relax +\let\unnumberedsubsec=\relax +\let\unnumberedsubsection=\relax +\let\unnumberedsubsubsec=\relax +\let\unnumberedsubsubsection=\relax +\let\section=\relax +\let\subsec=\relax +\let\subsubsec=\relax +\let\subsection=\relax +\let\subsubsection=\relax +\let\appendix=\relax +\let\appendixsec=\relax +\let\appendixsection=\relax +\let\appendixsubsec=\relax +\let\appendixsubsection=\relax +\let\appendixsubsubsec=\relax +\let\appendixsubsubsection=\relax +\let\contents=\relax +\let\smallbook=\relax +\let\titlepage=\relax +} + +% Used in nested conditionals, where we have to parse the Texinfo source +% and so want to turn off most commands, in case they are used +% incorrectly. +% +\def\ignoremorecommands{% + \let\defcv = \relax + \let\deffn = \relax + \let\deffnx = \relax + \let\defindex = \relax + \let\defivar = \relax + \let\defmac = \relax + \let\defmethod = \relax + \let\defop = \relax + \let\defopt = \relax + \let\defspec = \relax + \let\deftp = \relax + \let\deftypefn = \relax + \let\deftypefun = \relax + \let\deftypevar = \relax + \let\deftypevr = \relax + \let\defun = \relax + \let\defvar = \relax + \let\defvr = \relax + \let\ref = \relax + \let\xref = \relax + \let\printindex = \relax + \let\pxref = \relax + \let\settitle = \relax + \let\include = \relax + \let\lowersections = \relax + \let\down = \relax + \let\raisesections = \relax + \let\up = \relax + \let\set = \relax + \let\clear = \relax + \let\item = \relax + \let\message = \relax +} + +% Ignore @ignore ... @end ignore. +% +\def\ignore{\doignore{ignore}} + +% Also ignore @ifinfo, @ifhtml, @html, @menu, and @direntry text. +% +\def\ifinfo{\doignore{ifinfo}} +\def\ifhtml{\doignore{ifhtml}} +\def\html{\doignore{html}} +\def\menu{\doignore{menu}} +\def\direntry{\doignore{direntry}} + +% Ignore text until a line `@end #1'. +% +\def\doignore#1{\begingroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define a command to swallow text until we reach `@end #1'. + \long\def\doignoretext##1\end #1{\enddoignore}% + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \catcode32 = 10 + % + % And now expand that command. + \doignoretext +} + +% What we do to finish off ignored text. +% +\def\enddoignore{\endgroup\ignorespaces}% + +\newif\ifwarnedobs\warnedobsfalse +\def\obstexwarn{% + \ifwarnedobs\relax\else + % We need to warn folks that they may have trouble with TeX 3.0. + % This uses \immediate\write16 rather than \message to get newlines. + \immediate\write16{} + \immediate\write16{***WARNING*** for users of Unix TeX 3.0!} + \immediate\write16{This manual trips a bug in TeX version 3.0 (tex hangs).} + \immediate\write16{If you are running another version of TeX, relax.} + \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} + \immediate\write16{ Then upgrade your TeX installation if you can.} + \immediate\write16{If you are stuck with version 3.0, run the} + \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} + \immediate\write16{ to use a workaround.} + \immediate\write16{} + \warnedobstrue + \fi +} + +% **In TeX 3.0, setting text in \nullfont hangs tex. For a +% workaround (which requires the file ``dummy.tfm'' to be installed), +% uncomment the following line: +%%%%%\font\nullfont=dummy\let\obstexwarn=\relax + +% Ignore text, except that we keep track of conditional commands for +% purposes of nesting, up to an `@end #1' command. +% +\def\nestedignore#1{% + \obstexwarn + % We must actually expand the ignored text to look for the @end + % command, so that nested ignore constructs work. Thus, we put the + % text into a \vbox and then do nothing with the result. To minimize + % the change of memory overflow, we follow the approach outlined on + % page 401 of the TeXbook: make the current font be a dummy font. + % + \setbox0 = \vbox\bgroup + % Don't complain about control sequences we have declared \outer. + \ignoresections + % + % Define `@end #1' to end the box, which will in turn undefine the + % @end command again. + \expandafter\def\csname E#1\endcsname{\egroup\ignorespaces}% + % + % We are going to be parsing Texinfo commands. Most cause no + % trouble when they are used incorrectly, but some commands do + % complicated argument parsing or otherwise get confused, so we + % undefine them. + % + % We can't do anything about stray @-signs, unfortunately; + % they'll produce `undefined control sequence' errors. + \ignoremorecommands + % + % Set the current font to be \nullfont, a TeX primitive, and define + % all the font commands to also use \nullfont. We don't use + % dummy.tfm, as suggested in the TeXbook, because not all sites + % might have that installed. Therefore, math mode will still + % produce output, but that should be an extremely small amount of + % stuff compared to the main input. + % + \nullfont + \let\tenrm = \nullfont \let\tenit = \nullfont \let\tensl = \nullfont + \let\tenbf = \nullfont \let\tentt = \nullfont \let\smallcaps = \nullfont + \let\tensf = \nullfont + % Similarly for index fonts (mostly for their use in + % smallexample) + \let\indrm = \nullfont \let\indit = \nullfont \let\indsl = \nullfont + \let\indbf = \nullfont \let\indtt = \nullfont \let\indsc = \nullfont + \let\indsf = \nullfont + % + % Don't complain when characters are missing from the fonts. + \tracinglostchars = 0 + % + % Don't bother to do space factor calculations. + \frenchspacing + % + % Don't report underfull hboxes. + \hbadness = 10000 + % + % Do minimal line-breaking. + \pretolerance = 10000 + % + % Do not execute instructions in @tex + \def\tex{\doignore{tex}} +} + +% @set VAR sets the variable VAR to an empty value. +% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. +% +% Since we want to separate VAR from REST-OF-LINE (which might be +% empty), we can't just use \parsearg; we have to insert a space of our +% own to delimit the rest of the line, and then take it out again if we +% didn't need it. +% +\def\set{\parsearg\setxxx} +\def\setxxx#1{\setyyy#1 \endsetyyy} +\def\setyyy#1 #2\endsetyyy{% + \def\temp{#2}% + \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty + \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. + \fi +} +\def\setzzz#1#2 \endsetzzz{\expandafter\xdef\csname SET#1\endcsname{#2}} + +% @clear VAR clears (i.e., unsets) the variable VAR. +% +\def\clear{\parsearg\clearxxx} +\def\clearxxx#1{\global\expandafter\let\csname SET#1\endcsname=\relax} + +% @value{foo} gets the text saved in variable foo. +% +\def\value#1{\expandafter + \ifx\csname SET#1\endcsname\relax + {\{No value for ``#1''\}} + \else \csname SET#1\endcsname \fi} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +\def\ifset{\parsearg\ifsetxxx} +\def\ifsetxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifsetfail + \else + \expandafter\ifsetsucceed + \fi +} +\def\ifsetsucceed{\conditionalsucceed{ifset}} +\def\ifsetfail{\nestedignore{ifset}} +\defineunmatchedend{ifset} + +% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been +% defined with @set, or has been undefined with @clear. +% +\def\ifclear{\parsearg\ifclearxxx} +\def\ifclearxxx #1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \expandafter\ifclearsucceed + \else + \expandafter\ifclearfail + \fi +} +\def\ifclearsucceed{\conditionalsucceed{ifclear}} +\def\ifclearfail{\nestedignore{ifclear}} +\defineunmatchedend{ifclear} + +% @iftex always succeeds; we read the text following, through @end +% iftex). But `@end iftex' should be valid only after an @iftex. +% +\def\iftex{\conditionalsucceed{iftex}} +\defineunmatchedend{iftex} + +% We can't just want to start a group at @iftex (for example) and end it +% at @end iftex, since then @set commands inside the conditional have no +% effect (they'd get reverted at the end of the group). So we must +% define \Eiftex to redefine itself to be its previous value. (We can't +% just define it to fail again with an ``unmatched end'' error, since +% the @ifset might be nested.) +% +\def\conditionalsucceed#1{% + \edef\temp{% + % Remember the current value of \E#1. + \let\nece{prevE#1} = \nece{E#1}% + % + % At the `@end #1', redefine \E#1 to be its previous value. + \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% + }% + \temp +} + +% We need to expand lots of \csname's, but we don't want to expand the +% control sequences after we've constructed them. +% +\def\nece#1{\expandafter\noexpand\csname#1\endcsname} + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math means output in math mode. +% We don't use $'s directly in the definition of \math because control +% sequences like \math are expanded when the toc file is written. Then, +% we read the toc file back, the $'s will be normal characters (as they +% should be, according to the definition of Texinfo). So we must use a +% control sequence to switch into and out of math mode. +% +% This isn't quite enough for @math to work properly in indices, but it +% seems unlikely it will ever be needed there. +% +\let\implicitmath = $ +\def\math#1{\implicitmath #1\implicitmath} + +% @bullet and @minus need the same treatment as @math, just above. +\def\bullet{\implicitmath\ptexbullet\implicitmath} +\def\minus{\implicitmath-\implicitmath} + +\def\node{\ENVcheck\parsearg\nodezzz} +\def\nodezzz#1{\nodexxx [#1,]} +\def\nodexxx[#1,#2]{\gdef\lastnode{#1}} +\let\nwnode=\node +\let\lastnode=\relax + +\def\donoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\setref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\unnumbnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\unnumbsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +\def\appendixnoderef{\ifx\lastnode\relax\else +\expandafter\expandafter\expandafter\appendixsetref{\lastnode}\fi +\global\let\lastnode=\relax} + +\let\refill=\relax + +% @setfilename is done at the beginning of every texinfo file. +% So open here the files we need to have open while reading the input. +% This makes it possible to make a .fmt file for texinfo. +\def\setfilename{% + \readauxfile + \opencontents + \openindices + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \global\let\setfilename=\comment % Ignore extra @setfilename cmds. + \comment % Ignore the actual filename. +} + +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +\message{fonts,} + +% Font-change commands. + +% Texinfo supports the sans serif font style, which plain TeX does not. +% So we set up a \sf analogous to plain's \rm, etc. +\newfam\sffam +\def\sf{\fam=\sffam \tensf} +\let\li = \sf % Sometimes we call it \li, not \sf. + +%% Try out Computer Modern fonts at \magstephalf +\let\mainmagstep=\magstephalf + +% Set the font macro #1 to the font named #2, adding on the +% specified font prefix (normally `cm'). +\def\setfont#1#2{\font#1=\fontprefix#2} + +% Use cm as the default font prefix. +% To specify the font prefix, you must define \fontprefix +% before you read in texinfo.tex. +\ifx\fontprefix\undefined +\def\fontprefix{cm} +\fi + +\ifx\bigger\relax +\let\mainmagstep=\magstep1 +\setfont\textrm{r12} +\setfont\texttt{tt12} +\else +\setfont\textrm{r10 scaled \mainmagstep} +\setfont\texttt{tt10 scaled \mainmagstep} +\fi +% Instead of cmb10, you many want to use cmbx10. +% cmbx10 is a prettier font on its own, but cmb10 +% looks better when embedded in a line with cmr10. +\setfont\textbf{b10 scaled \mainmagstep} +\setfont\textit{ti10 scaled \mainmagstep} +\setfont\textsl{sl10 scaled \mainmagstep} +\setfont\textsf{ss10 scaled \mainmagstep} +\setfont\textsc{csc10 scaled \mainmagstep} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep + +% A few fonts for @defun, etc. +\setfont\defbf{bx10 scaled \magstep1} %was 1314 +\setfont\deftt{tt10 scaled \magstep1} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} + +% Fonts for indices and small examples. +% We actually use the slanted font rather than the italic, +% because texinfo normally uses the slanted fonts for that. +% Do not make many font distinctions in general in the index, since they +% aren't very useful. +\setfont\ninett{tt9} +\setfont\indrm{r9} +\setfont\indit{sl9} +\let\indsl=\indit +\let\indtt=\ninett +\let\indsf=\indrm +\let\indbf=\indrm +\setfont\indsc{csc10 at 9pt} +\font\indi=cmmi9 +\font\indsy=cmsy9 + +% Fonts for headings +\setfont\chaprm{bx12 scaled \magstep2} +\setfont\chapit{ti12 scaled \magstep2} +\setfont\chapsl{sl12 scaled \magstep2} +\setfont\chaptt{tt12 scaled \magstep2} +\setfont\chapsf{ss12 scaled \magstep2} +\let\chapbf=\chaprm +\setfont\chapsc{csc10 scaled\magstep3} +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 + +\setfont\secrm{bx12 scaled \magstep1} +\setfont\secit{ti12 scaled \magstep1} +\setfont\secsl{sl12 scaled \magstep1} +\setfont\sectt{tt12 scaled \magstep1} +\setfont\secsf{ss12 scaled \magstep1} +\setfont\secbf{bx12 scaled \magstep1} +\setfont\secsc{csc10 scaled\magstep2} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 + +% \setfont\ssecrm{bx10 scaled \magstep1} % This size an font looked bad. +% \setfont\ssecit{cmti10 scaled \magstep1} % The letters were too crowded. +% \setfont\ssecsl{sl10 scaled \magstep1} +% \setfont\ssectt{tt10 scaled \magstep1} +% \setfont\ssecsf{ss10 scaled \magstep1} + +%\setfont\ssecrm{b10 scaled 1315} % Note the use of cmb rather than cmbx. +%\setfont\ssecit{ti10 scaled 1315} % Also, the size is a little larger than +%\setfont\ssecsl{sl10 scaled 1315} % being scaled magstep1. +%\setfont\ssectt{tt10 scaled 1315} +%\setfont\ssecsf{ss10 scaled 1315} + +%\let\ssecbf=\ssecrm + +\setfont\ssecrm{bx12 scaled \magstephalf} +\setfont\ssecit{ti12 scaled \magstephalf} +\setfont\ssecsl{sl12 scaled \magstephalf} +\setfont\ssectt{tt12 scaled \magstephalf} +\setfont\ssecsf{ss12 scaled \magstephalf} +\setfont\ssecbf{bx12 scaled \magstephalf} +\setfont\ssecsc{csc10 scaled \magstep1} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled \magstep1 +% The smallcaps and symbol fonts should actually be scaled \magstep1.5, +% but that is not a standard magnification. + +% Fonts for title page: +\setfont\titlerm{bx12 scaled \magstep3} +\let\authorrm = \secrm + +% In order for the font changes to affect most math symbols and letters, +% we have to define the \textfont of the standard families. Since +% texinfo doesn't allow for producing subscripts and superscripts, we +% don't bother to reset \scriptfont and \scriptscriptfont (which would +% also require loading a lot more fonts). +% +\def\resetmathfonts{% + \textfont0 = \tenrm \textfont1 = \teni \textfont2 = \tensy + \textfont\itfam = \tenit \textfont\slfam = \tensl \textfont\bffam = \tenbf + \textfont\ttfam = \tentt \textfont\sffam = \tensf +} + + +% The font-changing commands redefine the meanings of \tenSTYLE, instead +% of just \STYLE. We do this so that font changes will continue to work +% in math mode, where it is the current \fam that is relevant in most +% cases, not the current. Plain TeX does, for example, +% \def\bf{\fam=\bffam \tenbf} By redefining \tenbf, we obviate the need +% to redefine \bf itself. +\def\textfonts{% + \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl + \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \resetmathfonts} +\def\chapfonts{% + \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl + \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy + \resetmathfonts} +\def\secfonts{% + \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl + \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \resetmathfonts} +\def\subsecfonts{% + \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl + \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \resetmathfonts} +\def\indexfonts{% + \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl + \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc + \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy + \resetmathfonts} + +% Set up the default fonts, so we can use them for creating boxes. +% +\textfonts + +% Count depth in font-changes, for error checks +\newcount\fontdepth \fontdepth=0 + +% Fonts for short table of contents. +\setfont\shortcontrm{r12} +\setfont\shortcontbf{bx12} +\setfont\shortcontsl{sl12} + +%% Add scribe-like font environments, plus @l for inline lisp (usually sans +%% serif) and @ii for TeX italic + +% \smartitalic{ARG} outputs arg in italics, followed by an italic correction +% unless the following character is such as not to need one. +\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi} +\def\smartitalic#1{{\sl #1}\futurelet\next\smartitalicx} + +\let\i=\smartitalic +\let\var=\smartitalic +\let\dfn=\smartitalic +\let\emph=\smartitalic +\let\cite=\smartitalic + +\def\b#1{{\bf #1}} +\let\strong=\b + +% We can't just use \exhyphenpenalty, because that only has effect at +% the end of a paragraph. Restore normal hyphenation at the end of the +% group within which \nohyphenation is presumably called. +% +\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} +\def\restorehyphenation{\hyphenchar\font = `- } + +\def\t#1{% + {\tt \nohyphenation \rawbackslash \frenchspacing #1}% + \null +} +\let\ttfont = \t +%\def\samp #1{`{\tt \rawbackslash \frenchspacing #1}'\null} +\def\samp #1{`\tclose{#1}'\null} +\def\key #1{{\tt \nohyphenation \uppercase{#1}}\null} +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + +\let\file=\samp + +% @code is a modification of @t, +% which makes spaces the same size as normal in the surrounding text. +\def\tclose#1{% + {% + % Change normal interword space to be same as for the current font. + \spaceskip = \fontdimen2\font + % + % Switch to typewriter. + \tt + % + % But `\ ' produces the large typewriter interword space. + \def\ {{\spaceskip = 0pt{} }}% + % + % Turn off hyphenation. + \nohyphenation + % + \rawbackslash + \frenchspacing + #1% + }% + \null +} + +% We *must* turn on hyphenation at `-' and `_' in \code. +% Otherwise, it is too hard to avoid overful hboxes +% in the Emacs manual, the Library manual, etc. + +% Unfortunately, TeX uses one parameter (\hyphenchar) to control +% both hyphenation at - and hyphenation within words. +% We must therefore turn them both off (\tclose does that) +% and arrange explicitly to hyphenate an a dash. +% -- rms. +{ +\catcode`\-=\active +\catcode`\_=\active +\global\def\code{\begingroup \catcode`\-=\active \let-\codedash \catcode`\_=\active \let_\codeunder \codex} +% The following is used by \doprintindex to insure that long function names +% wrap around. It is necessary for - and _ to be active before the index is +% read from the file, as \entry parses the arguments long before \code is +% ever called. -- mycroft +\global\def\indexbreaks{\catcode`\-=\active \let-\realdash \catcode`\_=\active \let_\realunder} +} +\def\realdash{-} +\def\realunder{_} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{\normalunderscore\discretionary{}{}{}} +\def\codex #1{\tclose{#1}\endgroup} + +%\let\exp=\tclose %Was temporary + +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. + +\def\xkey{\key} +\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% +\ifx\one\xkey\ifx\threex\three \key{#2}% +\else\tclose{\look}\fi +\else\tclose{\look}\fi} + +% Typeset a dimension, e.g., `in' or `pt'. The only reason for the +% argument is to make the input look right: @dmn{pt} instead of +% @dmn{}pt. +% +\def\dmn#1{\thinspace #1} + +\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} + +\def\l#1{{\li #1}\null} % + +\def\r#1{{\rm #1}} % roman font +% Use of \lowercase was suggested. +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +\message{page headings,} + +\newskip\titlepagetopglue \titlepagetopglue = 1.5in +\newskip\titlepagebottomglue \titlepagebottomglue = 2pc + +% First the title page. Must do @settitle before @titlepage. +\def\titlefont#1{{\titlerm #1}} + +\newif\ifseenauthor +\newif\iffinishedtitlepage + +\def\shorttitlepage{\parsearg\shorttitlepagezzz} +\def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} + +\def\titlepage{\begingroup \parindent=0pt \textfonts + \let\subtitlerm=\tenrm +% I deinstalled the following change because \cmr12 is undefined. +% This change was not in the ChangeLog anyway. --rms. +% \let\subtitlerm=\cmr12 + \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% + % + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% + % + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % + % Now you can print the title using @title. + \def\title{\parsearg\titlezzz}% + \def\titlezzz##1{\leftline{\titlefont{##1}} + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Now you can put text using @subtitle. + \def\subtitle{\parsearg\subtitlezzz}% + \def\subtitlezzz##1{{\subtitlefont \rightline{##1}}}% + % + % @author should come last, but may come many times. + \def\author{\parsearg\authorzzz}% + \def\authorzzz##1{\ifseenauthor\else\vskip 0pt plus 1filll\seenauthortrue\fi + {\authorfont \leftline{##1}}}% + % + % Most title ``pages'' are actually two pages long, with space + % at the top of the second. We don't want the ragged left on the second. + \let\oldpage = \page + \def\page{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + \oldpage + \let\page = \oldpage + \hbox{}}% +% \def\page{\oldpage \hbox{}} +} + +\def\Etitlepage{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + % It is important to do the page break before ending the group, + % because the headline and footline are only empty inside the group. + % If we use the new definition of \page, we always get a blank page + % after the title page, which we certainly don't want. + \oldpage + \endgroup + \HEADINGSon +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +%%% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks \evenheadline % Token sequence for heading line of even pages +\newtoks \oddheadline % Token sequence for heading line of odd pages +\newtoks \evenfootline % Token sequence for footing line of even pages +\newtoks \oddfootline % Token sequence for footing line of odd pages + +% Now make Tex use those variables +\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline + \else \the\evenheadline \fi}} +\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline + \else \the\evenfootline \fi}\HEADINGShook} +\let\HEADINGShook=\relax + +% Commands to set those variables. +% For example, this is what @headings on does +% @evenheading @thistitle|@thispage|@thischapter +% @oddheading @thischapter|@thispage|@thistitle +% @evenfooting @thisfile|| +% @oddfooting ||@thisfile + +\def\evenheading{\parsearg\evenheadingxxx} +\def\oddheading{\parsearg\oddheadingxxx} +\def\everyheading{\parsearg\everyheadingxxx} + +\def\evenfooting{\parsearg\evenfootingxxx} +\def\oddfooting{\parsearg\oddfootingxxx} +\def\everyfooting{\parsearg\everyfootingxxx} + +{\catcode`\@=0 % + +\gdef\evenheadingxxx #1{\evenheadingyyy #1@|@|@|@|\finish} +\gdef\evenheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddheadingxxx #1{\oddheadingyyy #1@|@|@|@|\finish} +\gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyheadingxxx #1{\everyheadingyyy #1@|@|@|@|\finish} +\gdef\everyheadingyyy #1@|#2@|#3@|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} +\gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} +\gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{% +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\gdef\everyfootingxxx #1{\everyfootingyyy #1@|@|@|@|\finish} +\gdef\everyfootingyyy #1@|#2@|#3@|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}} +\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} +% +}% unbind the catcode of @. + +% @headings double turns headings on for double-sided printing. +% @headings single turns headings on for single-sided printing. +% @headings off turns them off. +% @headings on same as @headings double, retained for compatibility. +% @headings after turns on double-sided headings after this page. +% @headings doubleafter turns on double-sided headings after this page. +% @headings singleafter turns on single-sided headings after this page. +% By default, they are off. + +\def\headings #1 {\csname HEADINGS#1\endcsname} + +\def\HEADINGSoff{ +\global\evenheadline={\hfil} \global\evenfootline={\hfil} +\global\oddheadline={\hfil} \global\oddfootline={\hfil}} +\HEADINGSoff +% When we turn headings on, set the page number to 1. +% For double-sided printing, put current file name in lower left corner, +% chapter name on inside top of right hand pages, document +% title on inside top of left hand pages, and page numbers on outside top +% edge of all pages. +\def\HEADINGSdouble{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +% For single-sided printing, chapter title goes across top left of page, +% page number on top right. +\def\HEADINGSsingle{ +%\pagealignmacro +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} +\def\HEADINGSon{\HEADINGSdouble} + +\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} +\let\HEADINGSdoubleafter=\HEADINGSafter +\def\HEADINGSdoublex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} +\def\HEADINGSsinglex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +} + +% Subroutines used in generating headings +% Produces Day Month Year style of output. +\def\today{\number\day\space +\ifcase\month\or +January\or February\or March\or April\or May\or June\or +July\or August\or September\or October\or November\or December\fi +\space\number\year} + +% Use this if you want the Month Day, Year style of output. +%\def\today{\ifcase\month\or +%January\or February\or March\or April\or May\or June\or +%July\or August\or September\or October\or November\or December\fi +%\space\number\day, \number\year} + +% @settitle line... specifies the title of the document, for headings +% It generates no output of its own + +\def\thistitle{No Title} +\def\settitle{\parsearg\settitlezzz} +\def\settitlezzz #1{\gdef\thistitle{#1}} + +\message{tables,} + +% @tabs -- simple alignment + +% These don't work. For one thing, \+ is defined as outer. +% So these macros cannot even be defined. + +%\def\tabs{\parsearg\tabszzz} +%\def\tabszzz #1{\settabs\+#1\cr} +%\def\tabline{\parsearg\tablinezzz} +%\def\tablinezzz #1{\+#1\cr} +%\def\&{&} + +% Tables -- @table, @ftable, @vtable, @item(x), @kitem(x), @xitem(x). + +% default indentation of table text +\newdimen\tableindent \tableindent=.8in +% default indentation of @itemize and @enumerate text +\newdimen\itemindent \itemindent=.3in +% margin between end of table item and start of table text. +\newdimen\itemmargin \itemmargin=.1in + +% used internally for \itemindent minus \itemmargin +\newdimen\itemmax + +% Note @table, @vtable, and @vtable define @item, @itemx, etc., with +% these defs. +% They also define \itemindex +% to index the item name in whatever manner is desired (perhaps none). + +\newif\ifitemxneedsnegativevskip + +\def\itemxpar{\par\ifitemxneedsnegativevskip\vskip-\parskip\nobreak\fi} + +\def\internalBitem{\smallbreak \parsearg\itemzzz} +\def\internalBitemx{\itemxpar \parsearg\itemzzz} + +\def\internalBxitem "#1"{\def\xitemsubtopix{#1} \smallbreak \parsearg\xitemzzz} +\def\internalBxitemx "#1"{\def\xitemsubtopix{#1} \itemxpar \parsearg\xitemzzz} + +\def\internalBkitem{\smallbreak \parsearg\kitemzzz} +\def\internalBkitemx{\itemxpar \parsearg\kitemzzz} + +\def\kitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \lastfunction}}% + \itemzzz {#1}} + +\def\xitemzzz #1{\dosubind {kw}{\code{#1}}{for {\bf \xitemsubtopic}}% + \itemzzz {#1}} + +\def\itemzzz #1{\begingroup % + \advance\hsize by -\rightskip + \advance\hsize by -\tableindent + \setbox0=\hbox{\itemfont{#1}}% + \itemindex{#1}% + \nobreak % This prevents a break before @itemx. + % + % Be sure we are not still in the middle of a paragraph. + %{\parskip = 0in + %\par + %}% + % + % If the item text does not fit in the space we have, put it on a line + % by itself, and do not allow a page break either before or after that + % line. We do not start a paragraph here because then if the next + % command is, e.g., @kindex, the whatsit would get put into the + % horizontal list on a line by itself, resulting in extra blank space. + \ifdim \wd0>\itemmax + % + % Make this a paragraph so we get the \parskip glue and wrapping, + % but leave it ragged-right. + \begingroup + \advance\leftskip by-\tableindent + \advance\hsize by\tableindent + \advance\rightskip by0pt plus1fil + \leavevmode\unhbox0\par + \endgroup + % + % We're going to be starting a paragraph, but we don't want the + % \parskip glue -- logically it's part of the @item we just started. + \nobreak \vskip-\parskip + % + % Stop a page break at the \parskip glue coming up. Unfortunately + % we can't prevent a possible page break at the following + % \baselineskip glue. + \nobreak + \endgroup + \itemxneedsnegativevskipfalse + \else + % The item text fits into the space. Start a paragraph, so that the + % following text (if any) will end up on the same line. Since that + % text will be indented by \tableindent, we make the item text be in + % a zero-width box. + \noindent + \rlap{\hskip -\tableindent\box0}\ignorespaces% + \endgroup% + \itemxneedsnegativevskiptrue% + \fi +} + +\def\item{\errmessage{@item while not in a table}} +\def\itemx{\errmessage{@itemx while not in a table}} +\def\kitem{\errmessage{@kitem while not in a table}} +\def\kitemx{\errmessage{@kitemx while not in a table}} +\def\xitem{\errmessage{@xitem while not in a table}} +\def\xitemx{\errmessage{@xitemx while not in a table}} + +%% Contains a kludge to get @end[description] to work +\def\description{\tablez{\dontindex}{1}{}{}{}{}} + +\def\table{\begingroup\inENV\obeylines\obeyspaces\tablex} +{\obeylines\obeyspaces% +\gdef\tablex #1^^M{% +\tabley\dontindex#1 \endtabley}} + +\def\ftable{\begingroup\inENV\obeylines\obeyspaces\ftablex} +{\obeylines\obeyspaces% +\gdef\ftablex #1^^M{% +\tabley\fnitemindex#1 \endtabley +\def\Eftable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\vtable{\begingroup\inENV\obeylines\obeyspaces\vtablex} +{\obeylines\obeyspaces% +\gdef\vtablex #1^^M{% +\tabley\vritemindex#1 \endtabley +\def\Evtable{\endgraf\afterenvbreak\endgroup}% +\let\Etable=\relax}} + +\def\dontindex #1{} +\def\fnitemindex #1{\doind {fn}{\code{#1}}}% +\def\vritemindex #1{\doind {vr}{\code{#1}}}% + +{\obeyspaces % +\gdef\tabley#1#2 #3 #4 #5 #6 #7\endtabley{\endgroup% +\tablez{#1}{#2}{#3}{#4}{#5}{#6}}} + +\def\tablez #1#2#3#4#5#6{% +\aboveenvbreak % +\begingroup % +\def\Edescription{\Etable}% Neccessary kludge. +\let\itemindex=#1% +\ifnum 0#3>0 \advance \leftskip by #3\mil \fi % +\ifnum 0#4>0 \tableindent=#4\mil \fi % +\ifnum 0#5>0 \advance \rightskip by #5\mil \fi % +\def\itemfont{#2}% +\itemmax=\tableindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \tableindent % +\exdentamount=\tableindent +\parindent = 0pt +\parskip = \smallskipamount +\ifdim \parskip=0pt \parskip=2pt \fi% +\def\Etable{\endgraf\afterenvbreak\endgroup}% +\let\item = \internalBitem % +\let\itemx = \internalBitemx % +\let\kitem = \internalBkitem % +\let\kitemx = \internalBkitemx % +\let\xitem = \internalBxitem % +\let\xitemx = \internalBxitemx % +} + +% This is the counter used by @enumerate, which is really @itemize + +\newcount \itemno + +\def\itemize{\parsearg\itemizezzz} + +\def\itemizezzz #1{% + \begingroup % ended by the @end itemsize + \itemizey {#1}{\Eitemize} +} + +\def\itemizey #1#2{% +\aboveenvbreak % +\itemmax=\itemindent % +\advance \itemmax by -\itemmargin % +\advance \leftskip by \itemindent % +\exdentamount=\itemindent +\parindent = 0pt % +\parskip = \smallskipamount % +\ifdim \parskip=0pt \parskip=2pt \fi% +\def#2{\endgraf\afterenvbreak\endgroup}% +\def\itemcontents{#1}% +\let\item=\itemizeitem} + +% Set sfcode to normal for the chars that usually have another value. +% These are `.?!:;,' +\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000 + \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 } + +% \splitoff TOKENS\endmark defines \first to be the first token in +% TOKENS, and \rest to be the remainder. +% +\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% + +% Allow an optional argument of an uppercase letter, lowercase letter, +% or number, to specify the first label in the enumerated list. No +% argument is the same as `1'. +% +\def\enumerate{\parsearg\enumeratezzz} +\def\enumeratezzz #1{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + \begingroup % ended by the @end enumerate + % + % If we were given no argument, pretend we were given `1'. + \def\thearg{#1}% + \ifx\thearg\empty \def\thearg{1}\fi + % + % Detect if the argument is a single token. If so, it might be a + % letter. Otherwise, the only valid thing it can be is a number. + % (We will always have one token, because of the test we just made. + % This is a good thing, since \splitoff doesn't work given nothing at + % all -- the first parameter is undelimited.) + \expandafter\splitoff\thearg\endmark + \ifx\rest\empty + % Only one token in the argument. It could still be anything. + % A ``lowercase letter'' is one whose \lccode is nonzero. + % An ``uppercase letter'' is one whose \lccode is both nonzero, and + % not equal to itself. + % Otherwise, we assume it's a number. + % + % We need the \relax at the end of the \ifnum lines to stop TeX from + % continuing to look for a <number>. + % + \ifnum\lccode\expandafter`\thearg=0\relax + \numericenumerate % a number (we hope) + \else + % It's a letter. + \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax + \lowercaseenumerate % lowercase letter + \else + \uppercaseenumerate % uppercase letter + \fi + \fi + \else + % Multiple tokens in the argument. We hope it's a number. + \numericenumerate + \fi +} + +% An @enumerate whose labels are integers. The starting integer is +% given in \thearg. +% +\def\numericenumerate{% + \itemno = \thearg + \startenumeration{\the\itemno}% +} + +% The starting (lowercase) letter is in \thearg. +\def\lowercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more lowercase letters in @enumerate; get a bigger + alphabet}% + \fi + \char\lccode\itemno + }% +} + +% The starting (uppercase) letter is in \thearg. +\def\uppercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more uppercase letters in @enumerate; get a bigger + alphabet} + \fi + \char\uccode\itemno + }% +} + +% Call itemizey, adding a period to the first argument and supplying the +% common last two arguments. Also subtract one from the initial value in +% \itemno, since @item increments \itemno. +% +\def\startenumeration#1{% + \advance\itemno by -1 + \itemizey{#1.}\Eenumerate\flushcr +} + +% @alphaenumerate and @capsenumerate are abbreviations for giving an arg +% to @enumerate. +% +\def\alphaenumerate{\enumerate{a}} +\def\capsenumerate{\enumerate{A}} +\def\Ealphaenumerate{\Eenumerate} +\def\Ecapsenumerate{\Eenumerate} + +% Definition of @item while inside @itemize. + +\def\itemizeitem{% +\advance\itemno by 1 +{\let\par=\endgraf \smallbreak}% +\ifhmode \errmessage{\in hmode at itemizeitem}\fi +{\parskip=0in \hskip 0pt +\hbox to 0pt{\hss \itemcontents\hskip \itemmargin}% +\vadjust{\penalty 1200}}% +\flushcr} + +% @multitable macros +% Amy Hendrickson, 8/18/94 +% +% @multitable ... @endmultitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width +% can be specified either with sample text given in a template line, +% or in percent of \hsize, the current width of text on page. + +% Table can continue over pages but will only break between lines. + +% To make preamble: +% +% Either define widths of columns in terms of percent of \hsize: +% @multitable @percentofhsize .2 .3 .5 +% @item ... +% +% Numbers following @percentofhsize are the percent of the total +% current hsize to be used for each column. You may use as many +% columns as desired. + +% Or use a template: +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item ... +% using the widest term desired in each column. + + +% Each new table line starts with @item, each subsequent new column +% starts with @tab. Empty columns may be produced by supplying @tab's +% with nothing between them for as many times as empty columns are needed, +% ie, @tab@tab@tab will produce two empty columns. + +% @item, @tab, @multicolumn or @endmulticolumn do not need to be on their +% own lines, but it will not hurt if they are. + +% Sample multitable: + +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item first col stuff @tab second col stuff @tab third col +% @item +% first col stuff +% @tab +% second col stuff +% @tab +% third col +% @item first col stuff @tab second col stuff +% @tab Many paragraphs of text may be used in any column. +% +% They will wrap at the width determined by the template. +% @item@tab@tab This will be in third column. +% @endmultitable + +% Default dimensions may be reset by user. +% @intableparskip will set vertical space between paragraphs in table. +% @intableparindent will set paragraph indent in table. +% @spacebetweencols will set horizontal space to be left between columns. +% @spacebetweenlines will set vertical space to be left between lines. + +%%%% +% Dimensions + +\newdimen\intableparskip +\newdimen\intableparindent +\newdimen\spacebetweencols +\newdimen\spacebetweenlines +\intableparskip=0pt +\intableparindent=6pt +\spacebetweencols=12pt +\spacebetweenlines=12pt + +%%%% +% Macros used to set up halign preamble: +\let\endsetuptable\relax +\def\xendsetuptable{\endsetuptable} +\let\percentofhsize\relax +\def\xpercentofhsize{\percentofhsize} +\newif\ifsetpercent + +\newcount\colcount +\def\setuptable#1{\def\firstarg{#1}% +\ifx\firstarg\xendsetuptable\let\go\relax% +\else + \ifx\firstarg\xpercentofhsize\global\setpercenttrue% + \else + \ifsetpercent + \if#1.\else% + \global\advance\colcount by1 % + \expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% + \fi + \else + \global\advance\colcount by1 + \setbox0=\hbox{#1}% + \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% + \fi% + \fi% + \let\go\setuptable% +\fi\go} +%%%% +% multitable syntax +\def\tab{&} + +%%%% +% @multitable ... @endmultitable definitions: + +\def\multitable#1\item{\bgroup +\let\item\cr +\tolerance=9500 +\hbadness=9500 +\parskip=\intableparskip +\parindent=\intableparindent +\overfullrule=0pt +\global\colcount=0\relax% +\def\Emultitable{\global\setpercentfalse\global\everycr{}\cr\egroup\egroup}% + % To parse everything between @multitable and @item : +\def\one{#1}\expandafter\setuptable\one\endsetuptable + % Need to reset this to 0 after \setuptable. +\global\colcount=0\relax% + % + % This preamble sets up a generic column definition, which will + % be used as many times as user calls for columns. + % \vtop will set a single line and will also let text wrap and + % continue for many paragraphs if desired. +\halign\bgroup&\global\advance\colcount by 1\relax% +\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname + % In order to keep entries from bumping into each other + % we will add a \leftskip of \spacebetweencols to all columns after + % the first one. + % If a template has been used, we will add \spacebetweencols + % to the width of each template entry. + % If user has set preamble in terms of percent of \hsize + % we will use that dimension as the width of the column, and + % the \leftskip will keep entries from bumping into each other. + % Table will start at left margin and final column will justify at + % right margin. +\ifnum\colcount=1 +\else + \ifsetpercent + \else + % If user has <not> set preamble in terms of percent of \hsize + % we will advance \hsize by \spacebetweencols + \advance\hsize by \spacebetweencols + \fi + % In either case we will make \leftskip=\spacebetweencols: +\leftskip=\spacebetweencols +\fi +\noindent##}\cr% + % \everycr will reset column counter, \colcount, at the end of + % each line. Every column entry will cause \colcount to advance by one. + % The table preamble + % looks at the current \colcount to find the correct column width. +\global\everycr{\noalign{\nointerlineskip\vskip\spacebetweenlines +\filbreak%% keeps underfull box messages off when table breaks over pages. +\global\colcount=0\relax}}} + +\message{indexing,} +% Index generation facilities + +% Define \newwrite to be identical to plain tex's \newwrite +% except not \outer, so it can be used within \newindex. +{\catcode`\@=11 +\gdef\newwrite{\alloc@7\write\chardef\sixt@@n}} + +% \newindex {foo} defines an index named foo. +% It automatically defines \fooindex such that +% \fooindex ...rest of line... puts an entry in the index foo. +% It also defines \fooindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is foo. +% The name of an index should be no more than 2 characters long +% for the sake of vms. + +\def\newindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#1}} +} + +% @defindex foo == \newindex{foo} + +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. + +\def\newcodeindex #1{ +\expandafter\newwrite \csname#1indfile\endcsname% Define number for output file +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#1}} +} + +\def\defcodeindex{\parsearg\newcodeindex} + +% @synindex foo bar makes index foo feed into index bar. +% Do this instead of @defindex foo if you don't want it as a separate index. +\def\synindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\doindex {#2}}% +} + +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +\def\syncodeindex #1 #2 {% +\expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname +\expandafter\let\csname#1indfile\endcsname=\synindexfoo +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\noexpand\docodeindex {#2}}% +} + +% Define \doindex, the driver for all \fooindex macros. +% Argument #1 is generated by the calling \fooindex macro, +% and it is "foo", the name of the index. + +% \doindex just uses \parsearg; it calls \doind for the actual work. +% This is because \doind is more useful to call from other macros. + +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. + +\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} +\def\singleindexer #1{\doind{\indexname}{#1}} + +% like the previous two, but they put @code around the argument. +\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} +\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} + +\def\indexdummies{% +% Take care of the plain tex accent commands. +\def\"{\realbackslash "}% +\def\`{\realbackslash `}% +\def\'{\realbackslash '}% +\def\^{\realbackslash ^}% +\def\~{\realbackslash ~}% +\def\={\realbackslash =}% +\def\b{\realbackslash b}% +\def\c{\realbackslash c}% +\def\d{\realbackslash d}% +\def\u{\realbackslash u}% +\def\v{\realbackslash v}% +\def\H{\realbackslash H}% +% Take care of the plain tex special European modified letters. +\def\oe{\realbackslash oe}% +\def\ae{\realbackslash ae}% +\def\aa{\realbackslash aa}% +\def\OE{\realbackslash OE}% +\def\AE{\realbackslash AE}% +\def\AA{\realbackslash AA}% +\def\o{\realbackslash o}% +\def\O{\realbackslash O}% +\def\l{\realbackslash l}% +\def\L{\realbackslash L}% +\def\ss{\realbackslash ss}% +% Take care of texinfo commands likely to appear in an index entry. +\def\_{{\realbackslash _}}% +\def\w{\realbackslash w }% +\def\bf{\realbackslash bf }% +\def\rm{\realbackslash rm }% +\def\sl{\realbackslash sl }% +\def\sf{\realbackslash sf}% +\def\tt{\realbackslash tt}% +\def\gtr{\realbackslash gtr}% +\def\less{\realbackslash less}% +\def\hat{\realbackslash hat}% +\def\char{\realbackslash char}% +\def\TeX{\realbackslash TeX}% +\def\dots{\realbackslash dots }% +\def\copyright{\realbackslash copyright }% +\def\tclose##1{\realbackslash tclose {##1}}% +\def\code##1{\realbackslash code {##1}}% +\def\samp##1{\realbackslash samp {##1}}% +\def\t##1{\realbackslash r {##1}}% +\def\r##1{\realbackslash r {##1}}% +\def\i##1{\realbackslash i {##1}}% +\def\b##1{\realbackslash b {##1}}% +\def\cite##1{\realbackslash cite {##1}}% +\def\key##1{\realbackslash key {##1}}% +\def\file##1{\realbackslash file {##1}}% +\def\var##1{\realbackslash var {##1}}% +\def\kbd##1{\realbackslash kbd {##1}}% +\def\dfn##1{\realbackslash dfn {##1}}% +\def\emph##1{\realbackslash emph {##1}}% +} + +% \indexnofonts no-ops all font-change commands. +% This is used when outputting the strings to sort the index by. +\def\indexdummyfont#1{#1} +\def\indexdummytex{TeX} +\def\indexdummydots{...} + +\def\indexnofonts{% +% Just ignore accents. +\let\"=\indexdummyfont +\let\`=\indexdummyfont +\let\'=\indexdummyfont +\let\^=\indexdummyfont +\let\~=\indexdummyfont +\let\==\indexdummyfont +\let\b=\indexdummyfont +\let\c=\indexdummyfont +\let\d=\indexdummyfont +\let\u=\indexdummyfont +\let\v=\indexdummyfont +\let\H=\indexdummyfont +% Take care of the plain tex special European modified letters. +\def\oe{oe}% +\def\ae{ae}% +\def\aa{aa}% +\def\OE{OE}% +\def\AE{AE}% +\def\AA{AA}% +\def\o{o}% +\def\O{O}% +\def\l{l}% +\def\L{L}% +\def\ss{ss}% +\let\w=\indexdummyfont +\let\t=\indexdummyfont +\let\r=\indexdummyfont +\let\i=\indexdummyfont +\let\b=\indexdummyfont +\let\emph=\indexdummyfont +\let\strong=\indexdummyfont +\let\cite=\indexdummyfont +\let\sc=\indexdummyfont +%Don't no-op \tt, since it isn't a user-level command +% and is used in the definitions of the active chars like <, >, |... +%\let\tt=\indexdummyfont +\let\tclose=\indexdummyfont +\let\code=\indexdummyfont +\let\file=\indexdummyfont +\let\samp=\indexdummyfont +\let\kbd=\indexdummyfont +\let\key=\indexdummyfont +\let\var=\indexdummyfont +\let\TeX=\indexdummytex +\let\dots=\indexdummydots +} + +% To define \realbackslash, we must make \ not be an escape. +% We must first make another character (@) an escape +% so we do not become unable to do a definition. + +{\catcode`\@=0 \catcode`\\=\other +@gdef@realbackslash{\}} + +\let\indexbackslash=0 %overridden during \printindex. + +\let\SETmarginindex=\relax %initialize! +% workhorse for all \fooindexes +% #1 is name of index, #2 is stuff to put there +\def\doind #1#2{% +% Put the index entry in the margin if desired. +\ifx\SETmarginindex\relax\else% +\insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% +\fi% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% Expand all macros now EXCEPT \folio +\def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now +% so it will be output as is; and it will print as backslash in the indx. +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}}}% +\temp }% +}\penalty\count10}} + +\def\dosubind #1#2#3{% +{\count10=\lastpenalty % +{\indexdummies % Must do this here, since \bf, etc expand at this stage +\escapechar=`\\% +{\let\folio=0% +\def\rawbackslashxx{\indexbackslash}% +% +% Now process the index-string once, with all font commands turned off, +% to get the string to sort the index by. +{\indexnofonts +\xdef\temp1{#2 #3}% +}% +% Now produce the complete index entry. We process the index-string again, +% this time with font commands expanded, to get what to print in the index. +\edef\temp{% +\write \csname#1indfile\endcsname{% +\realbackslash entry {\temp1}{\folio}{#2}{#3}}}% +\temp }% +}\penalty\count10}} + +% The index entry written in the file actually looks like +% \entry {sortstring}{page}{topic} +% or +% \entry {sortstring}{page}{topic}{subtopic} +% The texindex program reads in these files and writes files +% containing these kinds of lines: +% \initial {c} +% before the first topic whose initial is c +% \entry {topic}{pagelist} +% for a topic that is used without subtopics +% \primary {topic} +% for the beginning of a topic that is used with subtopics +% \secondary {subtopic}{pagelist} +% for each subtopic. + +% Define the user-accessible indexing commands +% @findex, @vindex, @kindex, @cindex. + +\def\findex {\fnindex} +\def\kindex {\kyindex} +\def\cindex {\cpindex} +\def\vindex {\vrindex} +\def\tindex {\tpindex} +\def\pindex {\pgindex} + +\def\cindexsub {\begingroup\obeylines\cindexsub} +{\obeylines % +\gdef\cindexsub "#1" #2^^M{\endgroup % +\dosubind{cp}{#2}{#1}}} + +% Define the macros used in formatting output of the sorted index material. + +% This is what you call to cause a particular index to get printed. +% Write +% @unnumbered Function Index +% @printindex fn + +\def\printindex{\parsearg\doprintindex} + +\def\doprintindex#1{% + \tex + \dobreak \chapheadingskip {10000} + \catcode`\%=\other\catcode`\&=\other\catcode`\#=\other + \catcode`\$=\other + \catcode`\~=\other + \indexbreaks + % + % The following don't help, since the chars were translated + % when the raw index was written, and their fonts were discarded + % due to \indexnofonts. + %\catcode`\"=\active + %\catcode`\^=\active + %\catcode`\_=\active + %\catcode`\|=\active + %\catcode`\<=\active + %\catcode`\>=\active + % % + \def\indexbackslash{\rawbackslashxx} + \indexfonts\rm \tolerance=9500 \advance\baselineskip -1pt + \begindoublecolumns + % + % See if the index file exists and is nonempty. + \openin 1 \jobname.#1s + \ifeof 1 + % \enddoublecolumns gets confused if there is no text in the index, + % and it loses the chapter title and the aux file entries for the + % index. The easiest way to prevent this problem is to make sure + % there is some text. + (Index is nonexistent) + \else + % + % If the index file exists but is empty, then \openin leaves \ifeof + % false. We have to make TeX try to read something from the file, so + % it can discover if there is anything in it. + \read 1 to \temp + \ifeof 1 + (Index is empty) + \else + \input \jobname.#1s + \fi + \fi + \closein 1 + \enddoublecolumns + \Etex +} + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +% Same as \bigskipamount except no shrink. +% \balancecolumns gets confused if there is any shrink. +\newskip\initialskipamount \initialskipamount 12pt plus4pt + +\def\initial #1{% +{\let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt +\ifdim\lastskip<\initialskipamount +\removelastskip \penalty-200 \vskip \initialskipamount\fi +\line{\secbf#1\hfill}\kern 2pt\penalty10000}} + +% This typesets a paragraph consisting of #1, dot leaders, and then #2 +% flush to the right margin. It is used for index and table of contents +% entries. The paragraph is indented by \leftskip. +% +\def\entry #1#2{\begingroup + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % Do not fill out the last line with white space. + \parfillskip = 0in + % + % No extra space above this paragraph. + \parskip = 0in + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % \hangindent is only relevant when the entry text and page number + % don't both fit on one line. In that case, bob suggests starting the + % dots pretty far over on the line. Unfortunately, a large + % indentation looks wrong when the entry text itself is broken across + % lines. So we use a small indentation and put up with long leaders. + % + % \hangafter is reset to 1 (which is the value we want) at the start + % of each paragraph, so we need not do anything with that. + \hangindent=2em + % + % When the entry text needs to be broken, just fill out the first line + % with blank space. + \rightskip = 0pt plus1fil + % + % Start a ``paragraph'' for the index entry so the line breaking + % parameters we've set above will have an effect. + \noindent + % + % Insert the text of the index entry. TeX will do line-breaking on it. + #1% + % The following is kluged to not output a line of dots in the index if + % there are no page numbers. The next person who breaks this will be + % cursed by a Unix daemon. + \def\tempa{{\rm }}% + \def\tempb{#2}% + \edef\tempc{\tempa}% + \edef\tempd{\tempb}% + \ifx\tempc\tempd\ \else% + % + % If we must, put the page number on a line of its own, and fill out + % this line with blank space. (The \hfil is overwhelmed with the + % fill leaders glue in \indexdotfill if the page number does fit.) + \hfil\penalty50 + \null\nobreak\indexdotfill % Have leaders before the page number. + % + % The `\ ' here is removed by the implicit \unskip that TeX does as + % part of (the primitive) \par. Without it, a spurious underfull + % \hbox ensues. + \ #2% The page number ends the paragraph. + \fi% + \par +\endgroup} + +% Like \dotfill except takes at least 1 em. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu ${\it .}$ \mkern1.5mu$}\hskip 1em plus 1fill} + +\def\primary #1{\line{#1\hfil}} + +\newskip\secondaryindent \secondaryindent=0.5cm + +\def\secondary #1#2{ +{\parfillskip=0in \parskip=0in +\hangindent =1in \hangafter=1 +\noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par +}} + +%% Define two-column mode, which is used in indexes. +%% Adapted from the TeXbook, page 416. +\catcode `\@=11 + +\newbox\partialpage + +\newdimen\doublecolumnhsize + +\def\begindoublecolumns{\begingroup + % Grab any single-column material above us. + \output = {\global\setbox\partialpage + =\vbox{\unvbox255\kern -\topskip \kern \baselineskip}}% + \eject + % + % Now switch to the double-column output routine. + \output={\doublecolumnout}% + % + % Change the page size parameters. We could do this once outside this + % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 + % format, but then we repeat the same computation. Repeating a couple + % of assignments once per index is clearly meaningless for the + % execution time, so we may as well do it once. + % + % First we halve the line length, less a little for the gutter between + % the columns. We compute the gutter based on the line length, so it + % changes automatically with the paper format. The magic constant + % below is chosen so that the gutter has the same value (well, +- < + % 1pt) as it did when we hard-coded it. + % + % We put the result in a separate register, \doublecolumhsize, so we + % can restore it in \pagesofar, after \hsize itself has (potentially) + % been clobbered. + % + \doublecolumnhsize = \hsize + \advance\doublecolumnhsize by -.04154\hsize + \divide\doublecolumnhsize by 2 + \hsize = \doublecolumnhsize + % + % Double the \vsize as well. (We don't need a separate register here, + % since nobody clobbers \vsize.) + \vsize = 2\vsize + \doublecolumnpagegoal +} + +\def\enddoublecolumns{\eject \endgroup \pagegoal=\vsize \unvbox\partialpage} + +\def\doublecolumnsplit{\splittopskip=\topskip \splitmaxdepth=\maxdepth + \global\dimen@=\pageheight \global\advance\dimen@ by-\ht\partialpage + \global\setbox1=\vsplit255 to\dimen@ \global\setbox0=\vbox{\unvbox1} + \global\setbox3=\vsplit255 to\dimen@ \global\setbox2=\vbox{\unvbox3} + \ifdim\ht0>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi + \ifdim\ht2>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi +} +\def\doublecolumnpagegoal{% + \dimen@=\vsize \advance\dimen@ by-2\ht\partialpage \global\pagegoal=\dimen@ +} +\def\pagesofar{\unvbox\partialpage % + \hsize=\doublecolumnhsize % have to restore this since output routine + \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}} +\def\doublecolumnout{% + \setbox5=\copy255 + {\vbadness=10000 \doublecolumnsplit} + \ifvbox255 + \setbox0=\vtop to\dimen@{\unvbox0} + \setbox2=\vtop to\dimen@{\unvbox2} + \onepageout\pagesofar \unvbox255 \penalty\outputpenalty + \else + \setbox0=\vbox{\unvbox5} + \ifvbox0 + \dimen@=\ht0 \advance\dimen@ by\topskip \advance\dimen@ by-\baselineskip + \divide\dimen@ by2 \splittopskip=\topskip \splitmaxdepth=\maxdepth + {\vbadness=10000 + \loop \global\setbox5=\copy0 + \setbox1=\vsplit5 to\dimen@ + \setbox3=\vsplit5 to\dimen@ + \ifvbox5 \global\advance\dimen@ by1pt \repeat + \setbox0=\vbox to\dimen@{\unvbox1} + \setbox2=\vbox to\dimen@{\unvbox3} + \global\setbox\partialpage=\vbox{\pagesofar} + \doublecolumnpagegoal + } + \fi + \fi +} + +\catcode `\@=\other +\message{sectioning,} +% Define chapters, sections, etc. + +\newcount \chapno +\newcount \secno \secno=0 +\newcount \subsecno \subsecno=0 +\newcount \subsubsecno \subsubsecno=0 + +% This counter is funny since it counts through charcodes of letters A, B, ... +\newcount \appendixno \appendixno = `\@ +\def\appendixletter{\char\the\appendixno} + +\newwrite \contentsfile +% This is called from \setfilename. +\def\opencontents{\openout \contentsfile = \jobname.toc} + +% Each @chapter defines this as the name of the chapter. +% page headings and footings can use it. @section does likewise + +\def\thischapter{} \def\thissection{} +\def\seccheck#1{\if \pageno<0 % +\errmessage{@#1 not allowed after generating table of contents}\fi +% +} + +\def\chapternofonts{% +\let\rawbackslash=\relax% +\let\frenchspacing=\relax% +\def\result{\realbackslash result} +\def\equiv{\realbackslash equiv} +\def\expansion{\realbackslash expansion} +\def\print{\realbackslash print} +\def\TeX{\realbackslash TeX} +\def\dots{\realbackslash dots} +\def\copyright{\realbackslash copyright} +\def\tt{\realbackslash tt} +\def\bf{\realbackslash bf } +\def\w{\realbackslash w} +\def\less{\realbackslash less} +\def\gtr{\realbackslash gtr} +\def\hat{\realbackslash hat} +\def\char{\realbackslash char} +\def\tclose##1{\realbackslash tclose {##1}} +\def\code##1{\realbackslash code {##1}} +\def\samp##1{\realbackslash samp {##1}} +\def\r##1{\realbackslash r {##1}} +\def\b##1{\realbackslash b {##1}} +\def\key##1{\realbackslash key {##1}} +\def\file##1{\realbackslash file {##1}} +\def\kbd##1{\realbackslash kbd {##1}} +% These are redefined because @smartitalic wouldn't work inside xdef. +\def\i##1{\realbackslash i {##1}} +\def\cite##1{\realbackslash cite {##1}} +\def\var##1{\realbackslash var {##1}} +\def\emph##1{\realbackslash emph {##1}} +\def\dfn##1{\realbackslash dfn {##1}} +} + +\newcount\absseclevel % used to calculate proper heading level +\newcount\secbase\secbase=0 % @raise/lowersections modify this count + +% @raisesections: treat @section as chapter, @subsection as section, etc. +\def\raisesections{\global\advance\secbase by -1} +\let\up=\raisesections % original BFox name + +% @lowersections: treat @chapter as section, @section as subsection, etc. +\def\lowersections{\global\advance\secbase by 1} +\let\down=\lowersections % original BFox name + +% Choose a numbered-heading macro +% #1 is heading level if unmodified by @raisesections or @lowersections +% #2 is text for heading +\def\numhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \chapterzzz{#2} +\or + \seczzz{#2} +\or + \numberedsubseczzz{#2} +\or + \numberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \chapterzzz{#2} + \else + \numberedsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses appendix heading levels +\def\apphead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \appendixzzz{#2} +\or + \appendixsectionzzz{#2} +\or + \appendixsubseczzz{#2} +\or + \appendixsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \appendixzzz{#2} + \else + \appendixsubsubseczzz{#2} + \fi +\fi +} + +% like \numhead, but chooses numberless heading levels +\def\unnmhead#1#2{\absseclevel=\secbase\advance\absseclevel by #1 +\ifcase\absseclevel + \unnumberedzzz{#2} +\or + \unnumberedseczzz{#2} +\or + \unnumberedsubseczzz{#2} +\or + \unnumberedsubsubseczzz{#2} +\else + \ifnum \absseclevel<0 + \unnumberedzzz{#2} + \else + \unnumberedsubsubseczzz{#2} + \fi +\fi +} + + +\def\thischaptername{No Chapter Title} +\outer\def\chapter{\parsearg\chapteryyy} +\def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz #1{\seccheck{chapter}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \chapno by 1 \message{\putwordChapter \the\chapno}% +\chapmacro {#1}{\the\chapno}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +% We don't substitute the actual chapter name into \thischapter +% because we don't want its macros evaluated now. +\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry {#1}{\the\chapno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec +}} + +\outer\def\appendix{\parsearg\appendixyyy} +\def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz +\def\appendixzzz #1{\seccheck{appendix}% +\secno=0 \subsecno=0 \subsubsecno=0 +\global\advance \appendixno by 1 \message{Appendix \appendixletter}% +\chapmacro {#1}{\putwordAppendix{} \appendixletter}% +\gdef\thissection{#1}% +\gdef\thischaptername{#1}% +\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% +{\chapternofonts% +\edef\temp{{\realbackslash chapentry + {#1}{\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\global\let\section = \appendixsec +\global\let\subsection = \appendixsubsec +\global\let\subsubsection = \appendixsubsubsec +}} + +\outer\def\top{\parsearg\unnumberedyyy} +\outer\def\unnumbered{\parsearg\unnumberedyyy} +\def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz +\def\unnumberedzzz #1{\seccheck{unnumbered}% +\secno=0 \subsecno=0 \subsubsecno=0 +% +% This used to be simply \message{#1}, but TeX fully expands the +% argument to \message. Therefore, if #1 contained @-commands, TeX +% expanded them. For example, in `@unnumbered The @cite{Book}', TeX +% expanded @cite (which turns out to cause errors because \cite is meant +% to be executed, not expanded). +% +% Anyway, we don't want the fully-expanded definition of @cite to appear +% as a result of the \message, we just want `@cite' itself. We use +% \the<toks register> to achieve this: TeX expands \the<toks> only once, +% simply yielding the contents of the <toks register>. +\toks0 = {#1}\message{(\the\toks0)}% +% +\unnumbchapmacro {#1}% +\gdef\thischapter{#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbchapentry {#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\global\let\section = \unnumberedsec +\global\let\subsection = \unnumberedsubsec +\global\let\subsubsection = \unnumberedsubsubsec +}} + +\outer\def\numberedsec{\parsearg\secyyy} +\def\secyyy #1{\numhead1{#1}} % normally calls seczzz +\def\seczzz #1{\seccheck{section}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\the\chapno}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appenixsection{\parsearg\appendixsecyyy} +\outer\def\appendixsec{\parsearg\appendixsecyyy} +\def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz +\def\appendixsectionzzz #1{\seccheck{appendixsection}% +\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % +\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% +{\chapternofonts% +\edef\temp{{\realbackslash secentry % +{#1}{\appendixletter}{\the\secno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} +\def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz +\def\unnumberedseczzz #1{\seccheck{unnumberedsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} +\def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz +\def\numberedsubseczzz #1{\seccheck{subsection}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} +\def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz +\def\appendixsubseczzz #1{\seccheck{appendixsubsec}% +\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % +\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsecentry % +{#1}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} +\def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz +\def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +\outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} +\def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz +\def\numberedsubsubseczzz #1{\seccheck{subsubsection}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry % + {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno} + {\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\donoderef % +\penalty 10000 % +}} + +\outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} +\def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz +\def\appendixsubsubseczzz #1{\seccheck{appendixsubsubsec}% +\gdef\thissection{#1}\global\advance \subsubsecno by 1 % +\subsubsecheading {#1} + {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% +{\chapternofonts% +\edef\temp{{\realbackslash subsubsecentry{#1}% + {\appendixletter} + {\the\secno}{\the\subsecno}{\the\subsubsecno}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\appendixnoderef % +\penalty 10000 % +}} + +\outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} +\def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz +\def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% +\plainsecheading {#1}\gdef\thissection{#1}% +{\chapternofonts% +\edef\temp{{\realbackslash unnumbsubsubsecentry{#1}{\noexpand\folio}}}% +\escapechar=`\\% +\write \contentsfile \temp % +\unnumbnoderef % +\penalty 10000 % +}} + +% These are variants which are not "outer", so they can appear in @ifinfo. +% Actually, they should now be obsolete; ordinary section commands should work. +\def\infotop{\parsearg\unnumberedzzz} +\def\infounnumbered{\parsearg\unnumberedzzz} +\def\infounnumberedsec{\parsearg\unnumberedseczzz} +\def\infounnumberedsubsec{\parsearg\unnumberedsubseczzz} +\def\infounnumberedsubsubsec{\parsearg\unnumberedsubsubseczzz} + +\def\infoappendix{\parsearg\appendixzzz} +\def\infoappendixsec{\parsearg\appendixseczzz} +\def\infoappendixsubsec{\parsearg\appendixsubseczzz} +\def\infoappendixsubsubsec{\parsearg\appendixsubsubseczzz} + +\def\infochapter{\parsearg\chapterzzz} +\def\infosection{\parsearg\sectionzzz} +\def\infosubsection{\parsearg\subsectionzzz} +\def\infosubsubsection{\parsearg\subsubsectionzzz} + +% These macros control what the section commands do, according +% to what kind of chapter we are in (ordinary, appendix, or unnumbered). +% Define them by default for a numbered chapter. +\global\let\section = \numberedsec +\global\let\subsection = \numberedsubsec +\global\let\subsubsection = \numberedsubsubsec + +% Define @majorheading, @heading and @subheading + +% NOTE on use of \vbox for chapter headings, section headings, and +% such: +% 1) We use \vbox rather than the earlier \line to permit +% overlong headings to fold. +% 2) \hyphenpenalty is set to 10000 because hyphenation in a +% heading is obnoxious; this forbids it. +% 3) Likewise, headings look best if no \parindent is used, and +% if justification is not attempted. Hence \raggedright. + + +\def\majorheading{\parsearg\majorheadingzzz} +\def\majorheadingzzz #1{% +{\advance\chapheadingskip by 10pt \chapbreak }% +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\chapheading{\parsearg\chapheadingzzz} +\def\chapheadingzzz #1{\chapbreak % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} + +\def\heading{\parsearg\secheadingi} + +\def\subheading{\parsearg\subsecheadingi} + +\def\subsubheading{\parsearg\subsubsecheadingi} + +% These macros generate a chapter, section, etc. heading only +% (including whitespace, linebreaking, etc. around it), +% given all the information in convenient, parsed form. + +%%% Args are the skip and penalty (usually negative) +\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} + +\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} + +%%% Define plain chapter starts, and page on/off switching for it +% Parameter controlling skip before chapter headings (if needed) + +\newskip \chapheadingskip \chapheadingskip = 30pt plus 8pt minus 4pt + +\def\chapbreak{\dobreak \chapheadingskip {-4000}} +\def\chappager{\par\vfill\supereject} +\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} + +\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} + +\def\CHAPPAGoff{ +\global\let\pchapsepmacro=\chapbreak +\global\let\pagealignmacro=\chappager} + +\def\CHAPPAGon{ +\global\let\pchapsepmacro=\chappager +\global\let\pagealignmacro=\chappager +\global\def\HEADINGSon{\HEADINGSsingle}} + +\def\CHAPPAGodd{ +\global\let\pchapsepmacro=\chapoddpage +\global\let\pagealignmacro=\chapoddpage +\global\def\HEADINGSon{\HEADINGSdouble}} + +\CHAPPAGon + +\def\CHAPFplain{ +\global\let\chapmacro=\chfplain +\global\let\unnumbchapmacro=\unnchfplain} + +\def\chfplain #1#2{% + \pchapsepmacro + {% + \chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #2\enspace #1}% + }% + \bigskip + \penalty5000 +} + +\def\unnchfplain #1{% +\pchapsepmacro % +{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} +\CHAPFplain % The default + +\def\unnchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 10000 % +} + +\def\chfopen #1#2{\chapoddpage {\chapfonts +\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% +\par\penalty 5000 % +} + +\def\CHAPFopen{ +\global\let\chapmacro=\chfopen +\global\let\unnumbchapmacro=\unnchfopen} + +% Parameter controlling skip before section headings. + +\newskip \subsecheadingskip \subsecheadingskip = 17pt plus 8pt minus 4pt +\def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} + +\newskip \secheadingskip \secheadingskip = 21pt plus 8pt minus 4pt +\def\secheadingbreak{\dobreak \secheadingskip {-1000}} + +% @paragraphindent is defined for the Info formatting commands only. +\let\paragraphindent=\comment + +% Section fonts are the base font at magstep2, which produces +% a size a bit more than 14 points in the default situation. + +\def\secheading #1#2#3{\secheadingi {#2.#3\enspace #1}} +\def\plainsecheading #1{\secheadingi {#1}} +\def\secheadingi #1{{\advance \secheadingskip by \parskip % +\secheadingbreak}% +{\secfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + + +% Subsection fonts are the base font at magstep1, +% which produces a size of 12 points. + +\def\subsecheading #1#2#3#4{\subsecheadingi {#2.#3.#4\enspace #1}} +\def\subsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } + +\def\subsubsecfonts{\subsecfonts} % Maybe this should change: + % Perhaps make sssec fonts scaled + % magstep half +\def\subsubsecheading #1#2#3#4#5{\subsubsecheadingi {#2.#3.#4.#5\enspace #1}} +\def\subsubsecheadingi #1{{\advance \subsecheadingskip by \parskip % +\subsecheadingbreak}% +{\subsubsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}% +\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000} + + +\message{toc printing,} + +% Finish up the main text and prepare to read what we've written +% to \contentsfile. + +\newskip\contentsrightmargin \contentsrightmargin=1in +\def\startcontents#1{% + \pagealignmacro + \immediate\closeout \contentsfile + \ifnum \pageno>0 + \pageno = -1 % Request roman numbered pages. + \fi + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \unnumbchapmacro{#1}\def\thischapter{}% + \begingroup % Set up to handle contents files properly. + \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 + \catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. +} + + +% Normal (long) toc. +\outer\def\contents{% + \startcontents{\putwordTableofContents}% + \input \jobname.toc + \endgroup + \vfill \eject +} + +% And just the chapters. +\outer\def\summarycontents{% + \startcontents{\putwordShortContents}% + % + \let\chapentry = \shortchapentry + \let\unnumbchapentry = \shortunnumberedentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl + \rm + \advance\baselineskip by 1pt % Open it up a little. + \def\secentry ##1##2##3##4{} + \def\unnumbsecentry ##1##2{} + \def\subsecentry ##1##2##3##4##5{} + \def\unnumbsubsecentry ##1##2{} + \def\subsubsecentry ##1##2##3##4##5##6{} + \def\unnumbsubsubsecentry ##1##2{} + \input \jobname.toc + \endgroup + \vfill \eject +} +\let\shortcontents = \summarycontents + +% These macros generate individual entries in the table of contents. +% The first argument is the chapter or section name. +% The last argument is the page number. +% The arguments in between are the chapter number, section number, ... + +% Chapter-level things, for both the long and short contents. +\def\chapentry#1#2#3{\dochapentry{#2\labelspace#1}{#3}} + +% See comments in \dochapentry re vbox and related settings +\def\shortchapentry#1#2#3{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno{#3}}% +} + +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g. `Appendix A' for an appendix, or `3' for a chapter. +% We could simplify the code here by writing out an \appendixentry +% command in the toc file for appendices, instead of using \chapentry +% for both, but it doesn't seem worth it. +\setbox0 = \hbox{\shortcontrm \putwordAppendix } +\newdimen\shortappendixwidth \shortappendixwidth = \wd0 + +\def\shortchaplabel#1{% + % We typeset #1 in a box of constant width, regardless of the text of + % #1, so the chapter titles will come out aligned. + \setbox0 = \hbox{#1}% + \dimen0 = \ifdim\wd0 > \shortappendixwidth \shortappendixwidth \else 0pt \fi + % + % This space should be plenty, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in in \shortchapentry above.) + \advance\dimen0 by 1.1em + \hbox to \dimen0{#1\hfil}% +} + +\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} +\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno{#2}}} + +% Sections. +\def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} +\def\unnumbsecentry#1#2{\dosecentry{#1}{#2}} + +% Subsections. +\def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} +\def\unnumbsubsecentry#1#2{\dosubsecentry{#1}{#2}} + +% And subsubsections. +\def\subsubsecentry#1#2#3#4#5#6{% + \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} +\def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} + + +% This parameter controls the indentation of the various levels. +\newdimen\tocindent \tocindent = 3pc + +% Now for the actual typesetting. In all these, #1 is the text and #2 is the +% page number. +% +% If the toc has to be broken over pages, we would want to be at chapters +% if at all possible; hence the \penalty. +\def\dochapentry#1#2{% + \penalty-300 \vskip\baselineskip + \begingroup + \chapentryfonts + \tocentry{#1}{\dopageno{#2}}% + \endgroup + \nobreak\vskip .25\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno{#2}}% +\endgroup} + +% Final typesetting of a toc entry; we use the same \entry macro as for +% the index entries, but we want to suppress hyphenation here. (We +% can't do that in the \entry macro, since index entries might consist +% of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) +% +\def\tocentry#1#2{\begingroup + \hyphenpenalty = 10000 + \entry{#1}{#2}% +\endgroup} + +% Space between chapter (or whatever) number and the title. +\def\labelspace{\hskip1em \relax} + +\def\dopageno#1{{\rm #1}} +\def\doshortpageno#1{{\rm #1}} + +\def\chapentryfonts{\secfonts \rm} +\def\secentryfonts{\textfonts} +\let\subsecentryfonts = \textfonts +\let\subsubsecentryfonts = \textfonts + + +\message{environments,} + +% Since these characters are used in examples, it should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% Furthermore, these definitions must come after we define our fonts. +\newbox\dblarrowbox \newbox\longdblarrowbox +\newbox\pushcharbox \newbox\bullbox +\newbox\equivbox \newbox\errorbox + +\let\ptexequiv = \equiv + +%{\tentt +%\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} +%\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} +%\global\setbox\pushcharbox = \hbox to 1em{\hfil$\dashv$\hfil} +%\global\setbox\equivbox = \hbox to 1em{\hfil$\ptexequiv$\hfil} +% Adapted from the manmac format (p.420 of TeXbook) +%\global\setbox\bullbox = \hbox to 1em{\kern.15em\vrule height .75ex width .85ex +% depth .1ex\hfil} +%} + +\def\point{$\star$} + +\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} + +\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} + +% Adapted from the TeXbook's \boxit. +{\tentt \global\dimen0 = 3em}% Width of the box. +\dimen2 = .55pt % Thickness of rules +% The text. (`r' is open on the right, `e' somewhat less so on the left.) +\setbox0 = \hbox{\kern-.75pt \tensf error\kern-1.5pt} + +\global\setbox\errorbox=\hbox to \dimen0{\hfil + \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. + \advance\hsize by -2\dimen2 % Rules. + \vbox{ + \hrule height\dimen2 + \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. + \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. + \kern3pt\vrule width\dimen2}% Space to right. + \hrule height\dimen2} + \hfil} + +% The @error{} command. +\def\error{\leavevmode\lower.7ex\copy\errorbox} + +% @tex ... @end tex escapes into raw Tex temporarily. +% One exception: @ is still an escape character, so that @end tex works. +% But \@ or @@ will get a plain tex @ character. + +\def\tex{\begingroup +\catcode `\\=0 \catcode `\{=1 \catcode `\}=2 +\catcode `\$=3 \catcode `\&=4 \catcode `\#=6 +\catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie +\catcode `\%=14 +\catcode 43=12 +\catcode`\"=12 +\catcode`\==12 +\catcode`\|=12 +\catcode`\<=12 +\catcode`\>=12 +\escapechar=`\\ +% +\let\~=\ptextilde +\let\{=\ptexlbrace +\let\}=\ptexrbrace +\let\.=\ptexdot +\let\*=\ptexstar +\let\dots=\ptexdots +\def\@{@}% +\let\bullet=\ptexbullet +\let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext \let\l=\ptexl +\let\L=\ptexL +% +\let\Etex=\endgroup} + +% Define @lisp ... @endlisp. +% @lisp does a \begingroup so it can rebind things, +% including the definition of @endlisp (which normally is erroneous). + +% Amount to narrow the margins by for @lisp. +\newskip\lispnarrowing \lispnarrowing=0.4in + +% This is the definition that ^^M gets inside @lisp, @example, and other +% such environments. \null is better than a space, since it doesn't +% have any width. +\def\lisppar{\null\endgraf} + +% Make each space character in the input produce a normal interword +% space in the output. Don't allow a line break at this space, as this +% is used only in environments like @example, where each line of input +% should produce a line of output anyway. +% +{\obeyspaces % +\gdef\sepspaces{\obeyspaces\let =\tie}} + +% Define \obeyedspace to be our active space, whatever it is. This is +% for use in \parsearg. +{\sepspaces% +\global\let\obeyedspace= } + +% This space is always present above and below environments. +\newskip\envskipamount \envskipamount = 0pt + +% Make spacing and below environment symmetrical. We use \parskip here +% to help in doing that, since in @example-like environments \parskip +% is reset to zero; thus the \afterenvbreak inserts no space -- but the +% start of the next paragraph will insert \parskip +% +\def\aboveenvbreak{{\advance\envskipamount by \parskip +\endgraf \ifdim\lastskip<\envskipamount +\removelastskip \penalty-50 \vskip\envskipamount \fi}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins. +\let\nonarrowing=\relax + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \cartouche: draw rectangle w/rounded corners around argument +\font\circle=lcircle10 +\newdimen\circthick +\newdimen\cartouter\newdimen\cartinner +\newskip\normbskip\newskip\normpskip\newskip\normlskip +\circthick=\fontdimen8\circle +% +\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth +\def\ctr{{\hskip 6pt\circle\char'010}} +\def\cbl{{\circle\char'012\hskip -6pt}} +\def\cbr{{\hskip 6pt\circle\char'011}} +\def\carttop{\hbox to \cartouter{\hskip\lskip + \ctl\leaders\hrule height\circthick\hfil\ctr + \hskip\rskip}} +\def\cartbot{\hbox to \cartouter{\hskip\lskip + \cbl\leaders\hrule height\circthick\hfil\cbr + \hskip\rskip}} +% +\newskip\lskip\newskip\rskip + +\long\def\cartouche{% +\begingroup + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt %we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18pt % allow for 3pt kerns on either +% side, and for 6pt waste from +% each corner char + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing=\comment + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \hsize=\cartinner + \kern3pt + \begingroup + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip +\def\Ecartouche{% + \endgroup + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup +\endgroup +}} + + +% This macro is called at the beginning of all the @example variants, +% inside a group. +\def\nonfillstart{% + \aboveenvbreak + \inENV % This group ends at the end of the body + \hfuzz = 12pt % Don't be fussy + \sepspaces % Make spaces be word-separators rather than space tokens. + \singlespace + \let\par = \lisppar % don't ignore blank lines + \obeylines % each line of input is a line of output + \parskip = 0pt + \parindent = 0pt + \emergencystretch = 0pt % don't try to avoid overfull boxes + % @cartouche defines \nonarrowing to inhibit narrowing + % at next level down. + \ifx\nonarrowing\relax + \advance \leftskip by \lispnarrowing + \exdentamount=\lispnarrowing + \let\exdent=\nofillexdent + \let\nonarrowing=\relax + \fi +} + +% To ending an @example-like environment, we first end the paragraph +% (via \afterenvbreak's vertical glue), and then the group. That way we +% keep the zero \parskip that the environments set -- \parskip glue +% will be inserted at the beginning of the next paragraph in the +% document, after the environment. +% +\def\nonfillfinish{\afterenvbreak\endgroup}% + +% This macro is +\def\lisp{\begingroup + \nonfillstart + \let\Elisp = \nonfillfinish + \tt + \rawbackslash % have \ input char produce \ char from current font + \gobble +} + +% Define the \E... control sequence only if we are inside the +% environment, so the error checking in \end will work. +% +% We must call \lisp last in the definition, since it reads the +% return following the @example (or whatever) command. +% +\def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} +\def\smallexample{\begingroup \def\Esmallexample{\nonfillfinish\endgroup}\lisp} +\def\smalllisp{\begingroup \def\Esmalllisp{\nonfillfinish\endgroup}\lisp} + +% @smallexample and @smalllisp. This is not used unless the @smallbook +% command is given. Originally contributed by Pavel@xerox. +% +\def\smalllispx{\begingroup + \nonfillstart + \let\Esmalllisp = \nonfillfinish + \let\Esmallexample = \nonfillfinish + % + % Smaller interline space and fonts for small examples. + \setleading{10pt}% + \indexfonts \tt + \rawbackslash % make \ output the \ character from the current font (tt) + \gobble +} + +% This is @display; same as @lisp except use roman font. +% +\def\display{\begingroup + \nonfillstart + \let\Edisplay = \nonfillfinish + \gobble +} + +% This is @format; same as @display except don't narrow margins. +% +\def\format{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eformat = \nonfillfinish + \gobble +} + +% @flushleft (same as @format) and @flushright. +% +\def\flushleft{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushleft = \nonfillfinish + \gobble +} +\def\flushright{\begingroup + \let\nonarrowing = t + \nonfillstart + \let\Eflushright = \nonfillfinish + \advance\leftskip by 0pt plus 1fill + \gobble} + +% @quotation does normal linebreaking (hence we can't use \nonfillstart) +% and narrows the margins. +% +\def\quotation{% + \begingroup\inENV %This group ends at the end of the @quotation body + {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip + \singlespace + \parindent=0pt + % We have retained a nonzero parskip for the environment, since we're + % doing normal filling. So to avoid extra space below the environment... + \def\Equotation{\parskip = 0pt \nonfillfinish}% + % + % @cartouche defines \nonarrowing to inhibit narrowing at next level down. + \ifx\nonarrowing\relax + \advance\leftskip by \lispnarrowing + \advance\rightskip by \lispnarrowing + \exdentamount = \lispnarrowing + \let\nonarrowing = \relax + \fi +} + +\message{defuns,} +% Define formatter for defuns +% First, allow user to change definition object font (\df) internally +\def\setdeffont #1 {\csname DEF#1\endcsname} + +\newskip\defbodyindent \defbodyindent=.4in +\newskip\defargsindent \defargsindent=50pt +\newskip\deftypemargin \deftypemargin=12pt +\newskip\deflastargmargin \deflastargmargin=18pt + +\newcount\parencount +% define \functionparens, which makes ( and ) and & do special things. +% \functionparens affects the group it is contained in. +\def\activeparens{% +\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active +\catcode`\[=\active \catcode`\]=\active} + +% Make control sequences which act like normal parenthesis chars. +\let\lparen = ( \let\rparen = ) + +{\activeparens % Now, smart parens don't turn on until &foo (see \amprm) + +% Be sure that we always have a definition for `(', etc. For example, +% if the fn name has parens in it, \boldbrax will not be in effect yet, +% so TeX would otherwise complain about undefined control sequence. +\global\let(=\lparen \global\let)=\rparen +\global\let[=\lbrack \global\let]=\rbrack + +\gdef\functionparens{\boldbrax\let&=\amprm\parencount=0 } +\gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} + +% Definitions of (, ) and & used in args for functions. +% This is the definition of ( outside of all parentheses. +\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested % +\global\advance\parencount by 1 } +% +% This is the definition of ( when already inside a level of parens. +\gdef\opnested{\char`\(\global\advance\parencount by 1 } +% +\gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. +% also in that case restore the outer-level definition of (. +\ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi +\global\advance \parencount by -1 } +% If we encounter &foo, then turn on ()-hacking afterwards +\gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } +% +\gdef\normalparens{\boldbrax\let&=\ampnr} +} % End of definition inside \activeparens +%% These parens (in \boldbrax) actually are a little bolder than the +%% contained text. This is especially needed for [ and ] +\def\opnr{{\sf\char`\(}} \def\clnr{{\sf\char`\)}} \def\ampnr{\&} +\def\lbrb{{\bf\char`\[}} \def\rbrb{{\bf\char`\]}} + +% First, defname, which formats the header line itself. +% #1 should be the function name. +% #2 should be the type of definition, such as "Function". + +\def\defname #1#2{% +% Get the values of \leftskip and \rightskip as they were +% outside the @def... +\dimen2=\leftskip +\advance\dimen2 by -\defbodyindent +\dimen3=\rightskip +\advance\dimen3 by -\defbodyindent +\noindent % +\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% +\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line +\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations +\parshape 2 0in \dimen0 \defargsindent \dimen1 % +% Now output arg 2 ("Function" or some such) +% ending at \deftypemargin from the right margin, +% but stuck inside a box of width 0 so it does not interfere with linebreaking +{% Adjust \hsize to exclude the ambient margins, +% so that \rightline will obey them. +\advance \hsize by -\dimen2 \advance \hsize by -\dimen3 +\rlap{\rightline{{\rm #2}\hskip \deftypemargin}}}% +% Make all lines underfull and no complaints: +\tolerance=10000 \hbadness=10000 +\advance\leftskip by -\defbodyindent +\exdentamount=\defbodyindent +{\df #1}\enskip % Generate function name +} + +% Actually process the body of a definition +% #1 should be the terminating control sequence, such as \Edefun. +% #2 should be the "another name" control sequence, such as \defunx. +% #3 should be the control sequence that actually processes the header, +% such as \defunheader. + +\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % 61 is `=' +\obeylines\activeparens\spacesplit#3} + +\def\defmethparsebody #1#2#3#4 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} + +\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} + +% These parsing functions are similar to the preceding ones +% except that they do not make parens into active characters. +% These are used for "variables" since they have no arguments. + +\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2{\begingroup\obeylines\spacesplit#3}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup % +\catcode 61=\active % +\obeylines\spacesplit#3} + +% This is used for \def{tp,vr}parsebody. It could probably be used for +% some of the others, too, with some judicious conditionals. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV % + \medbreak % + % Define the end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% + \parindent=0in + \advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent + \exdentamount=\defbodyindent + \begingroup\obeylines +} + +\def\defvrparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{#3{#4}}% +} + +% This loses on `@deftp {Data Type} {struct termios}' -- it thinks the +% type is just `struct', because we lose the braces in `{struct +% termios}' when \spacesplit reads its undelimited argument. Sigh. +% \let\deftpparsebody=\defvrparsebody +% +% So, to get around this, we put \empty in with the type name. That +% way, TeX won't find exactly `{...}' as an undelimited argument, and +% won't strip off the braces. +% +\def\deftpparsebody #1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \spacesplit{\parsetpheaderline{#3{#4}}}\empty +} + +% Fine, but then we have to eventually remove the \empty *and* the +% braces (if any). That's what this does, putting the result in \tptemp. +% +\def\removeemptybraces\empty#1\relax{\def\tptemp{#1}}% + +% After \spacesplit has done its work, this is called -- #1 is the final +% thing to call, #2 the type name (which starts with \empty), and #3 +% (which might be empty) the arguments. +% +\def\parsetpheaderline#1#2#3{% + \removeemptybraces#2\relax + #1{\tptemp}{#3}% +}% + +\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % +\medbreak % +% Define the end token that this defining construct specifies +% so that it will exit this group. +\def#1{\endgraf\endgroup\medbreak}% +\def#2##1 ##2 {\def#4{##1}% +\begingroup\obeylines\spacesplit{#3{##2}}}% +\parindent=0in +\advance\leftskip by \defbodyindent \advance \rightskip by \defbodyindent +\exdentamount=\defbodyindent +\begingroup\obeylines\spacesplit{#3{#5}}} + +% Split up #2 at the first space token. +% call #1 with two arguments: +% the first is all of #2 before the space token, +% the second is all of #2 after that space token. +% If #2 contains no space token, all of it is passed as the first arg +% and the second is passed as empty. + +{\obeylines +\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% +\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% +\ifx\relax #3% +#1{#2}{}\else #1{#2}{#3#4}\fi}} + +% So much for the things common to all kinds of definitions. + +% Define @defun. + +% First, define the processing that is wanted for arguments of \defun +% Use this to expand the args and terminate the paragraph they make up + +\def\defunargs #1{\functionparens \sl +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +\hyphenchar\tensl=0 +#1% +\hyphenchar\tensl=45 +\ifnum\parencount=0 \else \errmessage{unbalanced parens in @def arguments}\fi% +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +\def\deftypefunargs #1{% +% Expand, preventing hyphenation at `-' chars. +% Note that groups don't affect changes in \hyphenchar. +% Use \boldbrax, not \functionparens, so that & is not special. +\boldbrax +\tclose{#1}% avoid \code because of side effects on active chars +\interlinepenalty=10000 +\advance\rightskip by 0pt plus 1fil +\endgraf\penalty 10000\vskip -\parskip\penalty 10000% +} + +% Do complete processing of one @defun or @defunx line already parsed. + +% @deffn Command forward-char nchars + +\def\deffn{\defmethparsebody\Edeffn\deffnx\deffnheader} + +\def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% +\begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defun == @deffn Function + +\def\defun{\defparsebody\Edefun\defunx\defunheader} + +\def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Function}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefun int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefun{\defparsebody\Edeftypefun\deftypefunx\deftypefunheader} + +% #1 is the data type. #2 is the name and args. +\def\deftypefunheader #1#2{\deftypefunheaderx{#1}#2 \relax} +% #1 is the data type, #2 the name, #3 the args. +\def\deftypefunheaderx #1#2 #3\relax{% +\doind {fn}{\code{#2}}% Make entry in function index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Function}% +\deftypefunargs {#3}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) + +\def\deftypefn{\defmethparsebody\Edeftypefn\deftypefnx\deftypefnheader} + +% \defheaderxcond#1\relax$$$ +% puts #1 in @code, followed by a space, but does nothing if #1 is null. +\def\defheaderxcond#1#2$$${\ifx#1\relax\else\code{#1#2} \fi} + +% #1 is the classification. #2 is the data type. #3 is the name and args. +\def\deftypefnheader #1#2#3{\deftypefnheaderx{#1}{#2}#3 \relax} +% #1 is the classification, #2 the data type, #3 the name, #4 the args. +\def\deftypefnheaderx #1#2#3 #4\relax{% +\doind {fn}{\code{#3}}% Make entry in function index +\begingroup +\normalparens % notably, turn off `&' magic, which prevents +% at least some C++ text from working +\defname {\defheaderxcond#2\relax$$$#3}{#1}% +\deftypefunargs {#4}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defmac == @deffn Macro + +\def\defmac{\defparsebody\Edefmac\defmacx\defmacheader} + +\def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Macro}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% @defspec == @deffn Special Form + +\def\defspec{\defparsebody\Edefspec\defspecx\defspecheader} + +\def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index +\begingroup\defname {#1}{Special Form}% +\defunargs {#2}\endgroup % +\catcode 61=\other % Turn off change made in \defparsebody +} + +% This definition is run if you use @defunx +% anywhere other than immediately after a @defun or @defunx. + +\def\deffnx #1 {\errmessage{@deffnx in invalid context}} +\def\defunx #1 {\errmessage{@defunx in invalid context}} +\def\defmacx #1 {\errmessage{@defmacx in invalid context}} +\def\defspecx #1 {\errmessage{@defspecx in invalid context}} +\def\deftypefnx #1 {\errmessage{@deftypefnx in invalid context}} +\def\deftypeunx #1 {\errmessage{@deftypeunx in invalid context}} + +% @defmethod, and so on + +% @defop {Funny Method} foo-class frobnicate argument + +\def\defop #1 {\def\defoptype{#1}% +\defopparsebody\Edefop\defopx\defopheader\defoptype} + +\def\defopheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% Make entry in function index +\begingroup\defname {#2}{\defoptype{} on #1}% +\defunargs {#3}\endgroup % +} + +% @defmethod == @defop Method + +\def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} + +\def\defmethodheader #1#2#3{% +\dosubind {fn}{\code{#2}}{on #1}% entry in function index +\begingroup\defname {#2}{Method on #1}% +\defunargs {#3}\endgroup % +} + +% @defcv {Class Option} foo-class foo-flag + +\def\defcv #1 {\def\defcvtype{#1}% +\defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} + +\def\defcvarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{\defcvtype{} of #1}% +\defvarargs {#3}\endgroup % +} + +% @defivar == @defcv {Instance Variable} + +\def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} + +\def\defivarheader #1#2#3{% +\dosubind {vr}{\code{#2}}{of #1}% Make entry in var index +\begingroup\defname {#2}{Instance Variable of #1}% +\defvarargs {#3}\endgroup % +} + +% These definitions are run if you use @defmethodx, etc., +% anywhere other than immediately after a @defmethod, etc. + +\def\defopx #1 {\errmessage{@defopx in invalid context}} +\def\defmethodx #1 {\errmessage{@defmethodx in invalid context}} +\def\defcvx #1 {\errmessage{@defcvx in invalid context}} +\def\defivarx #1 {\errmessage{@defivarx in invalid context}} + +% Now @defvar + +% First, define the processing that is wanted for arguments of @defvar. +% This is actually simple: just print them in roman. +% This must expand the args and terminate the paragraph they make up +\def\defvarargs #1{\normalparens #1% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000} + +% @defvr Counter foo-count + +\def\defvr{\defvrparsebody\Edefvr\defvrx\defvrheader} + +\def\defvrheader #1#2#3{\doind {vr}{\code{#2}}% +\begingroup\defname {#2}{#1}\defvarargs{#3}\endgroup} + +% @defvar == @defvr Variable + +\def\defvar{\defvarparsebody\Edefvar\defvarx\defvarheader} + +\def\defvarheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{Variable}% +\defvarargs {#2}\endgroup % +} + +% @defopt == @defvr {User Option} + +\def\defopt{\defvarparsebody\Edefopt\defoptx\defoptheader} + +\def\defoptheader #1#2{\doind {vr}{\code{#1}}% Make entry in var index +\begingroup\defname {#1}{User Option}% +\defvarargs {#2}\endgroup % +} + +% @deftypevar int foobar + +\def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} + +% #1 is the data type. #2 is the name. +\def\deftypevarheader #1#2{% +\doind {vr}{\code{#2}}% Make entry in variables index +\begingroup\defname {\defheaderxcond#1\relax$$$#2}{Variable}% +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% @deftypevr {Global Flag} int enable + +\def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} + +\def\deftypevrheader #1#2#3{\doind {vr}{\code{#3}}% +\begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1} +\interlinepenalty=10000 +\endgraf\penalty 10000\vskip -\parskip\penalty 10000 +\endgroup} + +% This definition is run if you use @defvarx +% anywhere other than immediately after a @defvar or @defvarx. + +\def\defvrx #1 {\errmessage{@defvrx in invalid context}} +\def\defvarx #1 {\errmessage{@defvarx in invalid context}} +\def\defoptx #1 {\errmessage{@defoptx in invalid context}} +\def\deftypevarx #1 {\errmessage{@deftypevarx in invalid context}} +\def\deftypevrx #1 {\errmessage{@deftypevrx in invalid context}} + +% Now define @deftp +% Args are printed in bold, a slight difference from @defvar. + +\def\deftpargs #1{\bf \defvarargs{#1}} + +% @deftp Class window height width ... + +\def\deftp{\deftpparsebody\Edeftp\deftpx\deftpheader} + +\def\deftpheader #1#2#3{\doind {tp}{\code{#2}}% +\begingroup\defname {#2}{#1}\deftpargs{#3}\endgroup} + +% This definition is run if you use @deftpx, etc +% anywhere other than immediately after a @deftp, etc. + +\def\deftpx #1 {\errmessage{@deftpx in invalid context}} + +\message{cross reference,} +% Define cross-reference macros +\newwrite \auxfile + +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% \setref{foo} defines a cross-reference point named foo. + +\def\setref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ysectionnumberandtype}} + +\def\unnumbsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Ynothing}} + +\def\appendixsetref#1{% +\dosetq{#1-title}{Ytitle}% +\dosetq{#1-pg}{Ypagenumber}% +\dosetq{#1-snt}{Yappendixletterandtype}} + +% \xref, \pxref, and \ref generate cross-references to specified points. +% For \xrefX, #1 is the node name, #2 the name of the Info +% cross-reference, #3 the printed node name, #4 the name of the Info +% file, #5 the name of the printed manual. All but the node name can be +% omitted. +% +\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} +\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} +\def\ref#1{\xrefX[#1,,,,,,,]} +\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup + \def\printedmanual{\ignorespaces #5}% + \def\printednodename{\ignorespaces #3}% + \setbox1=\hbox{\printedmanual}% + \setbox0=\hbox{\printednodename}% + \ifdim \wd0 = 0pt + % No printed node name was explicitly given. + \ifx\SETxref-automatic-section-title\relax % + % Use the actual chapter/section title appear inside + % the square brackets. Use the real section title if we have it. + \ifdim \wd1>0pt% + % It is in another manual, so we don't have it. + \def\printednodename{\ignorespaces #1}% + \else + \ifhavexrefs + % We know the real title if we have the xref values. + \def\printednodename{\refx{#1-title}}% + \else + % Otherwise just copy the Info node name. + \def\printednodename{\ignorespaces #1}% + \fi% + \fi + \def\printednodename{#1-title}% + \else + % Use the node name inside the square brackets. + \def\printednodename{\ignorespaces #1}% + \fi + \fi + % + % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not + % insert empty discretionaries after hyphens, which means that it will + % not find a line break at a hyphen in a node names. Since some manuals + % are best written with fairly long node names, containing hyphens, this + % is a loss. Therefore, we give the text of the node name again, so it + % is as if TeX is seeing it for the first time. + \ifdim \wd1 > 0pt + \putwordsection{} ``\printednodename'' in \cite{\printedmanual}% + \else + % _ (for example) has to be the character _ for the purposes of the + % control sequence corresponding to the node, but it has to expand + % into the usual \leavevmode...\vrule stuff for purposes of + % printing. So we \turnoffactive for the \refx-snt, back on for the + % printing, back off for the \refx-pg. + {\turnoffactive \refx{#1-snt}{}}% + \space [\printednodename],\space + \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \fi +\endgroup} + +% \dosetq is the interface for calls from other macros + +% Use \turnoffactive so that punctuation chars such as underscore +% work in node names. +\def\dosetq #1#2{{\let\folio=0 \turnoffactive \auxhat% +\edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% +\next}} + +% \internalsetq {foo}{page} expands into +% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...} +% When the aux file is read, ' is the escape character + +\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}} + +% Things to be expanded by \internalsetq + +\def\Ypagenumber{\folio} + +\def\Ytitle{\thissection} + +\def\Ynothing{} + +\def\Ysectionnumberandtype{% +\ifnum\secno=0 \putwordChapter\xreftie\the\chapno % +\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\def\Yappendixletterandtype{% +\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}% +\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno % +\else \ifnum \subsubsecno=0 % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno % +\else % +\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno % +\fi \fi \fi } + +\gdef\xreftie{'tie} + +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\thisisundefined + \let\linenumber = \empty % Non-3.0. +\else + \def\linenumber{\the\inputlineno:\space} +\fi + +% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. +% If its value is nonempty, SUFFIX is output afterward. + +\def\refx#1#2{% + \expandafter\ifx\csname X#1\endcsname\relax + % If not defined, say something at least. + $\langle$un\-de\-fined$\rangle$% + \ifhavexrefs + \message{\linenumber Undefined cross reference `#1'.}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \else + % It's defined, so just use it. + \csname X#1\endcsname + \fi + #2% Output the suffix in any case. +} + +% Read the last existing aux file, if any. No error if none exists. + +% This is the macro invoked by entries in the aux file. +\def\xrdef #1#2{ +{\catcode`\'=\other\expandafter \gdef \csname X#1\endcsname {#2}}} + +\def\readauxfile{% +\begingroup +\catcode `\^^@=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\^^C=\other +\catcode `\^^D=\other +\catcode `\^^E=\other +\catcode `\^^F=\other +\catcode `\^^G=\other +\catcode `\^^H=\other +\catcode `\ =\other +\catcode `\^^L=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode `\=\other +\catcode 26=\other +\catcode `\^^[=\other +\catcode `\^^\=\other +\catcode `\^^]=\other +\catcode `\^^^=\other +\catcode `\^^_=\other +\catcode `\@=\other +\catcode `\^=\other +\catcode `\~=\other +\catcode `\[=\other +\catcode `\]=\other +\catcode`\"=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode `\$=\other +\catcode `\#=\other +\catcode `\&=\other +% `\+ does not work, so use 43. +\catcode 43=\other +% Make the characters 128-255 be printing characters +{% + \count 1=128 + \def\loop{% + \catcode\count 1=\other + \advance\count 1 by 1 + \ifnum \count 1<256 \loop \fi + }% +}% +% the aux file uses ' as the escape. +% Turn off \ as an escape so we do not lose on +% entries which were dumped with control sequences in their names. +% For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ +% Reference to such entries still does not work the way one would wish, +% but at least they do not bomb out when the aux file is read in. +\catcode `\{=1 \catcode `\}=2 +\catcode `\%=\other +\catcode `\'=0 +\catcode`\^=7 % to make ^^e4 etc usable in xref tags +\catcode `\\=\other +\openin 1 \jobname.aux +\ifeof 1 \else \closein 1 \input \jobname.aux \global\havexrefstrue +\global\warnedobstrue +\fi +% Open the new aux file. Tex will close it automatically at exit. +\openout \auxfile=\jobname.aux +\endgroup} + + +% Footnotes. + +\newcount \footnoteno + +% The trailing space in the following definition for supereject is +% vital for proper filling; pages come out unaligned when you do a +% pagealignmacro call if that space before the closing brace is +% removed. +\def\supereject{\par\penalty -20000\footnoteno =0 } + +% @footnotestyle is meaningful for info output only.. +\let\footnotestyle=\comment + +\let\ptexfootnote=\footnote + +{\catcode `\@=11 +% +% Auto-number footnotes. Otherwise like plain. +\gdef\footnote{% + \global\advance\footnoteno by \@ne + \edef\thisfootno{$^{\the\footnoteno}$}% + % + % In case the footnote comes at the end of a sentence, preserve the + % extra spacing after we do the footnote number. + \let\@sf\empty + \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi + % + % Remove inadvertent blank space before typesetting the footnote number. + \unskip + \thisfootno\@sf + \footnotezzz +}% + +% Don't bother with the trickery in plain.tex to not require the +% footnote text as a parameter. Our footnotes don't need to be so general. +% +\long\gdef\footnotezzz#1{\insert\footins{% + % We want to typeset this text as a normal paragraph, even if the + % footnote reference occurs in (for example) a display environment. + % So reset some parameters. + \interlinepenalty\interfootnotelinepenalty + \splittopskip\ht\strutbox % top baseline for broken footnotes + \splitmaxdepth\dp\strutbox + \floatingpenalty\@MM + \leftskip\z@skip + \rightskip\z@skip + \spaceskip\z@skip + \xspaceskip\z@skip + \parindent\defaultparindent + % + % Hang the footnote text off the number. + \hang + \textindent{\thisfootno}% + % + % Don't crash into the line above the footnote text. Since this + % expands into a box, it must come within the paragraph, lest it + % provide a place where TeX can split the footnote. + \footstrut + #1\strut}% +} + +}%end \catcode `\@=11 + +% Set the baselineskip to #1, and the lineskip and strut size +% correspondingly. There is no deep meaning behind these magic numbers +% used as factors; they just match (closely enough) what Knuth defined. +% +\def\lineskipfactor{.08333} +\def\strutheightpercent{.70833} +\def\strutdepthpercent {.29167} +% +\def\setleading#1{% + \normalbaselineskip = #1\relax + \normallineskip = \lineskipfactor\normalbaselineskip + \normalbaselines + \setbox\strutbox =\hbox{% + \vrule width0pt height\strutheightpercent\baselineskip + depth \strutdepthpercent \baselineskip + }% +} + +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt} + + +% End of control word definitions. + +\message{and turning on texinfo input format.} + +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% Set some numeric style parameters, for 8.5 x 11 format. + +%\hsize = 6.5in +\newdimen\defaultparindent \defaultparindent = 15pt +\parindent = \defaultparindent +\parskip 18pt plus 1pt +\setleading{15pt} +\advance\topskip by 1.2cm + +% Prevent underfull vbox error messages. +\vbadness=10000 + +% Following George Bush, just get rid of widows and orphans. +\widowpenalty=10000 +\clubpenalty=10000 + +% Use TeX 3.0's \emergencystretch to help line breaking, but if we're +% using an old version of TeX, don't do anything. We want the amount of +% stretch added to depend on the line length, hence the dependence on +% \hsize. This makes it come to about 9pt for the 8.5x11 format. +% +\ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% +\else + \emergencystretch = \hsize + \divide\emergencystretch by 45 +\fi + +% Use @smallbook to reset parameters for 7x9.5 format (or else 7x9.25) +\def\smallbook{ + +% These values for secheadingskip and subsecheadingskip are +% experiments. RJC 7 Aug 1992 +\global\secheadingskip = 17pt plus 6pt minus 3pt +\global\subsecheadingskip = 14pt plus 6pt minus 3pt + +\global\lispnarrowing = 0.3in +\setleading{12pt} +\advance\topskip by -1cm +\global\parskip 3pt plus 1pt +\global\hsize = 5in +\global\vsize=7.5in +\global\tolerance=700 +\global\hfuzz=1pt +\global\contentsrightmargin=0pt +\global\deftypemargin=0pt +\global\defbodyindent=.5cm + +\global\pagewidth=\hsize +\global\pageheight=\vsize + +\global\let\smalllisp=\smalllispx +\global\let\smallexample=\smalllispx +\global\def\Esmallexample{\Esmalllisp} +} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{ +\global\tolerance=700 +\global\hfuzz=1pt +\setleading{12pt} +\global\parskip 15pt plus 1pt + +\global\vsize= 53\baselineskip +\advance\vsize by \topskip +%\global\hsize= 5.85in % A4 wide 10pt +\global\hsize= 6.5in +\global\outerhsize=\hsize +\global\advance\outerhsize by 0.5in +\global\outervsize=\vsize +\global\advance\outervsize by 0.6in + +\global\pagewidth=\hsize +\global\pageheight=\vsize +} + +% Allow control of the text dimensions. Parameters in order: textheight; +% textwidth; \voffset; \hoffset (!); binding offset. All require a dimension; +% header is additional; added length extends the bottom of the page. + +\def\changepagesizes#1#2#3#4#5{ + \global\vsize= #1 + \advance\vsize by \topskip + \global\voffset= #3 + \global\hsize= #2 + \global\outerhsize=\hsize + \global\advance\outerhsize by 0.5in + \global\outervsize=\vsize + \global\advance\outervsize by 0.6in + \global\pagewidth=\hsize + \global\pageheight=\vsize + \global\normaloffset= #4 + \global\bindingoffset= #5} + +% This layout is compatible with Latex on A4 paper. + +\def\afourlatex{\changepagesizes{22cm}{15cm}{7mm}{4.6mm}{5mm}} + +% Use @afourwide to print on European A4 paper in wide format. +\def\afourwide{\afourpaper +\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}} + +% Define macros to output various characters with catcode for normal text. +\catcode`\"=\other +\catcode`\~=\other +\catcode`\^=\other +\catcode`\_=\other +\catcode`\|=\other +\catcode`\<=\other +\catcode`\>=\other +\catcode`\+=\other +\def\normaldoublequote{"} +\def\normaltilde{~} +\def\normalcaret{^} +\def\normalunderscore{_} +\def\normalverticalbar{|} +\def\normalless{<} +\def\normalgreater{>} +\def\normalplus{+} + +% This macro is used to make a character print one way in ttfont +% where it can probably just be output, and another way in other fonts, +% where something hairier probably needs to be done. +% +% #1 is what to print if we are indeed using \tt; #2 is what to print +% otherwise. Since all the Computer Modern typewriter fonts have zero +% interword stretch (and shrink), and it is reasonable to expect all +% typewriter fonts to have this, we can check that font parameter. +% +\def\ifusingtt#1#2{\ifdim \fontdimen3\the\font=0pt #1\else #2\fi} + +% Turn off all special characters except @ +% (and those which the user can use as if they were ordinary). +% Most of these we simply print from the \tt font, but for some, we can +% use math or other variants that look better in normal text. + +\catcode`\"=\active +\def\activedoublequote{{\tt \char '042}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt \char '176}} +\chardef\hat=`\^ +\catcode`\^=\active +\def\auxhat{\def^{'hat}} +\def^{{\tt \hat}} + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +% Subroutine for the previous macro. +\def\_{\lvvmode \kern.06em \vbox{\hrule width.3em height.1ex}} + +% \lvvmode is equivalent in function to \leavevmode. +% Using \leavevmode runs into trouble when written out to +% an index file due to the expansion of \leavevmode into ``\unhbox +% \voidb@x'' ---which looks to TeX like ``\unhbox \voidb\x'' due to our +% magic tricks with @. +\def\lvvmode{\vbox to 0pt{}} + +\catcode`\|=\active +\def|{{\tt \char '174}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +%\catcode 27=\active +%\def^^[{$\diamondsuit$} + +% Set up an active definition for =, but don't enable it most of the time. +{\catcode`\==\active +\global\def={{\tt \char 61}}} + +% If a .fmt file is being used, characters that might appear in a file +% name cannot be active until we have parsed the command line. +% So turn them off again, and have \everyjob (or @setfilename) turn them on. +% \otherifyactive is called near the end of this file. +\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} + +\catcode`\@=0 + +% \rawbackslashxx output one backslash character in current font +\global\chardef\rawbackslashxx=`\\ +%{\catcode`\\=\other +%@gdef@rawbackslashxx{\}} + +% \rawbackslash redefines \ as input to do \rawbackslashxx. +{\catcode`\\=\active +@gdef@rawbackslash{@let\=@rawbackslashxx }} + +% \normalbackslash outputs one backslash in fixed width font. +\def\normalbackslash{{\tt\rawbackslashxx}} + +% Say @foo, not \foo, in error messages. +\escapechar=`\@ + +% \catcode 17=0 % Define control-q +\catcode`\\=\active + +% Used sometimes to turn off (effectively) the active characters +% even after parsing them. +@def@turnoffactive{@let"=@normaldoublequote +@let\=@realbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +@def@normalturnoffactive{@let"=@normaldoublequote +@let\=@normalbackslash +@let~=@normaltilde +@let^=@normalcaret +@let_=@normalunderscore +@let|=@normalverticalbar +@let<=@normalless +@let>=@normalgreater +@let+=@normalplus} + +% Make _ and + \other characters, temporarily. +% This is canceled by @fixbackslash. +@otherifyactive + +% If a .fmt file is being used, we don't want the `\input texinfo' to show up. +% That is what \eatinput is for; after that, the `\' should revert to printing +% a backslash. +% +@gdef@eatinput input texinfo{@fixbackslash} +@global@let\ = @eatinput + +% On the other hand, perhaps the file did not have a `\input texinfo'. Then +% the first `\{ in the file would cause an error. This macro tries to fix +% that, assuming it is called before the first `\' could plausibly occur. +% Also back turn on active characters that might appear in the input +% file name, in case not using a pre-dumped format. +% +@gdef@fixbackslash{@ifx\@eatinput @let\ = @normalbackslash @fi + @catcode`+=@active @catcode`@_=@active} + +%% These look ok in all fonts, so just make them not special. The @rm below +%% makes sure that the current font starts out as the newly loaded cmr10 +@catcode`@$=@other @catcode`@%=@other @catcode`@&=@other @catcode`@#=@other + +@textfonts +@rm + +@c Local variables: +@c page-delimiter: "^\\\\message" +@c End: