Mercurial > hg > octave-terminal
changeset 2670:18192eea4973
[project @ 1997-02-13 18:29:53 by jwe]
line wrap: on
line diff
--- a/doc/conf.texi.in +++ b/doc/conf.texi.in @@ -4,3 +4,4 @@ @set VERSION %OCTAVE_VERSION% @set OCTAVEHOME %OCTAVE_HOME% +@set TARGETHOSTTYPE %TARGET_HOST_TYPE%
--- a/doc/interpreter/Makefile.in +++ b/doc/interpreter/Makefile.in @@ -20,14 +20,15 @@ SOURCES = -TEXINFO = amuse.texi arith.texi audio.texi basics.texi bugs.texi \ - control.texi cp-idx.texi diffeq.texi emacs.texi expr.texi \ - extend.texi fn-idx.texi func.texi image.texi install.texi \ - intro.texi invoke.texi io.texi linalg.texi matrix.texi \ - nonlin.texi octave.texi op-idx.texi optim.texi plot.texi \ - poly.texi preface.texi program.texi quad.texi set.texi \ - signal.texi special.texi stats.texi stmt.texi strings.texi \ - system.texi var.texi vr-idx.texi +TEXINFO = arith.texi audio.texi basics.texi bugs.texi control.texi \ + cp-idx.texi data.texi diffeq.texi emacs.texi errors.texi \ + eval.texi expr.texi fn-idx.texi func.texi gpl.texi \ + grammar.texi image.texi install.texi intro.texi io.texi \ + linalg.texi matrix.texi nonlin.texi numbers.texi octave.texi \ + op-idx.texi optim.texi plot.texi poly.texi preface.texi \ + quad.texi set.texi signal.texi stats.texi stmt.texi \ + strings.texi struct.texi system.texi tips.texi var.texi \ + vr-idx.texi FORMATTED = octave.dvi octave.ps octave.info octave.info octave.info-[0-9]* @@ -64,7 +65,8 @@ @echo "Making conf.texi from conf.texi.in..." @(version_val=${version}; \ sed < $(srcdir)/../conf.texi.in > conf.texi.tmp \ - -e "s;%OCTAVE_VERSION%;$$version_val;" \ + -e "s;%OCTAVE_VERSION%;${version_val};" \ + -e "s;%TARGET_HOST_TYPE%;${target_host_type};" \ -e "s;%OCTAVE_HOME%;${prefix};") @if test "$(srcdir)" = "." ; then \ $(top_srcdir)/move-if-change conf.texi.tmp conf.texi; \
--- a/doc/interpreter/amuse.texi +++ b/doc/interpreter/amuse.texi @@ -1,9 +1,9 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 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 +@node Amusements, Tips, Programming Utilities, Top @chapter Amusements @cindex lottery numbers
--- a/doc/interpreter/arith.texi +++ b/doc/interpreter/arith.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Arithmetic, Linear Algebra, String Functions, Top +@node Arithmetic, Linear Algebra, Matrix Manipulation, Top @chapter Arithmetic Unless otherwise noted, all of the functions described in this chapter @@ -625,7 +625,7 @@ 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}. +cleared @xref{Status of Variables}. @end defvr @defvr {Built-in Variable} Inf
--- a/doc/interpreter/audio.texi +++ b/doc/interpreter/audio.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 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. @@ -82,7 +82,7 @@ @deftypefn {Function File} {} 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 +8kHz. The program waits until the user types @kbd{RET} and then immediately starts to record. @end deftypefn
--- a/doc/interpreter/basics.texi +++ b/doc/interpreter/basics.texi @@ -1,160 +1,906 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Basics, Expressions, Invoking Octave, Top -@chapter Basics +@node Getting Started, Data Types, Introduction, Top +@chapter Getting Started + +This chapter explains some of Octave's basic features, including how to +start an Octave session, get help at the command prompt, edit the +command line, and write Octave programs that can be executed as commands +from your shell. @menu -* Comments:: -* Executable Octave Programs:: +* Invoking Octave:: +* Quitting Octave:: +* Getting Help:: +* Command Line Editing:: * Errors:: -* Help:: -* Command Line Editing:: -* Command History Functions:: +* Executable Octave Programs:: +* Comments:: +@end menu + +@node Invoking Octave, Quitting Octave, Getting Started, Getting Started +@section 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 by using the command-line +options described in the next section, and Octave itself can remind you +of the options available. Type @kbd{octave --help} to display all +available options and briefly describe their use (@kbd{octave -h} is a +shorter equivalent). + +@menu +* Command Line Options:: +* Startup Files:: @end menu -@node Comments, Executable Octave Programs, Basics, Basics -@section Comments in Octave Programs -@cindex @samp{#} -@cindex @samp{%} -@cindex comments -@cindex use of comments -@cindex documenting Octave programs -@cindex programs +@node Command Line Options, Startup Files, Invoking Octave, Invoking Octave +@subsection Command Line Options +@cindex Octave command options +@cindex command options +@cindex options, Octave command + +Here is a complete list of all the command line options that Octave +accepts. + +@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. -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. +@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. -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}: +@item --help +@itemx -h +@itemx -? +@cindex @code{--help} +@cindex @code{-h} +@cindex @code{-?} +Print short help message and exit. + +@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. -@smallexample -function xdot = f (x, t) +@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. -# usage: f (x, t) -# -# This function defines the right-hand-side functions for a set of -# nonlinear differential equations. +@item --interactive +@itemx -i +@cindex @code{--interactive} +@cindex @code{-i} +Force interactive behavior. - r = 0.25 +@item --no-init-file +@cindex @code{--no-init-file} +Don't read the @file{~/.octaverc} or @file{.octaverc} files. + +@item --no-line-editing +@cindex @code{--no-line-editing} +Disable command-line editing and history. + +@item --no-site-file +@cindex @code{--no-site-file} +Don't read the site-wide @file{octaverc} file. - and so on... - -endfunction -@end smallexample +@item --norc +@itemx -f +@cindex @code{--norc} +@cindex @code{-f} +Don't read any of the system or user initialization files at startup. +This is equivalent to using both of the options @code{--no-init-file} +and @code{--no-site-file}. -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 +@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 +@itemx --braindead +@cindex @code{--traditional} +@cindex @code{--braindead} +Set initial values for user-preference variables to the following +values for compatibility with @sc{Matlab}. @example -help f +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 + +Octave also includes several built-in variables that contain information +about the command line, including the number of arguments and all of the +options. + +@defvr {Built-in Variable} 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 -produces the output - -@smallexample - usage: f (x, t) +@code{argv} would be a string vector with the elements +@code{--no-line-editing} and @code{--silent}. - This function defines the right-hand-side functions for a set of - nonlinear differential equations. -@end smallexample +If you write an executable Octave script, @code{argv} will contain the +list of arguments passed to the script. @pxref{Executable Octave Programs}. +@end defvr -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. +@defvr {Built-in Variable} nargin +At the top level, this variable is defined as the number of command line +arguments that were passed to Octave. +@end defvr -@node Executable Octave Programs, Errors, Comments, Basics -@section Executable Octave Programs -@cindex executable scripts -@cindex scripts -@cindex self contained programs -@cindex program, self contained -@cindex @samp{#!} +@defvr {Built-in Variable} program_invocation_name +@defvrx {Built-in Variable} program_name +When Octave starts, the value of the built-in variable +@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 +@kbd{@value{OCTAVEHOME}/bin/octave} to start Octave, +@code{program_invocation_name} would have the value +@code{"@value{OCTAVEHOME}/bin/octave"}, and @code{program_name} would +have the value @code{"octave"}. -Once you have learned Octave, you may want to write self-contained -Octave scripts, using the @samp{#!} script mechanism. You can do this -on GNU systems and 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.} +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. +@end defvr -For example, you could create a text file named @file{hello}, containing -the following lines: +Here is an example of using these variables to reproduce Octave's +command line. @example -@group -#! @value{OCTAVEHOME}/bin/octave -qf - -# a sample Octave program -printf ("Hello, world!\n"); -@end group -@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 as if you had -typed: - -@example -octave hello -@end example - -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}. Note that some -operating systems may place a limit on the number of characters that are -recognized after @samp{#!}. - -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. - -If you invoke an executable Octave script with command line arguments, -the arguments are available in the built-in variable @var{argv}. -@xref{Command Line Options}. For example, the following program will -reproduce the command line that is used to execute it. - -@example -@group -#! @value{OCTAVEHOME}/bin/octave -qf - printf ("%s", program_name); for i = 1:nargin printf (" %s", argv(i,:)); endfor printf ("\n"); -@end group @end example -@node Errors, Help, Executable Octave Programs, Basics -@section Errors +@noindent +@xref{Index Expressions} for an explanation of how to properly index +arrays of strings and substrings in Octave. + +@node Startup Files, , Command Line Options, Invoking Octave +@subsection 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/share/octave/site/m/startup/octaverc +Where @code{OCTAVE_HOME} is the directory in which all of Octave is +installed (the default is @file{/usr/local}). This file is provided so +that changes to the default Octave environment can be made globally for +all users at your site for all versions of Octave you have installed. +Some care should be taken when making changes to this file, since all +users of Octave at your site will be affected. + +@item OCTAVE_HOME/share/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 for a +particular version of Octave. 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 in the current +directory after it reads @file{~/.octaverc}. 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 the startup 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 function +definitions. + +@node Quitting Octave, Getting Help, Invoking Octave, Getting Started +@section Quitting Octave +@cindex exiting octave +@cindex quitting octave + +@deftypefn {Built-in Function} {} exit (@var{status}) +@deftypefnx {Built-in Function} {} quit (@var{status}) +Exit the current Octave session. If the optional integer value +@var{status} is supplied, pass that value to the operating system as the +Octave's exit status. +@end deftypefn + +@deftypefn {Built-in Function} {} atexit (@var{fcn}) +Register function to be called when Octave exits. +@end deftypefn + +@node Getting Help, Command Line Editing, Quitting Octave, Getting Started +@section Commands for Getting Help +@cindex on-line help +@cindex help, on-line + +The entire text of this manual is available from the Octave prompt +via the command @kbd{help -i}. In addition, the documentation for +individual user-written functions and variables is also available via +the @kbd{help} command. This section describes the commands used for +reading the manual and the documentation strings for user-supplied +functions and variables. @xref{Function Files}, for more information +about how to document the functions you write. + +@deffn {Command} 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 @kbd{help help} prints a short message +describing the @code{help} command, and @kbd{help -i help} starts the +GNU Info browser at this node in the on-line version of the manual. + +Once the GNU Info browser is runnig, help for using it is available +using the command @kbd{C-h}. +@end deffn + +The help command can give you information about operators, but not the +comma and semicolons that are used as command separators. To get help +for those, you must type @kbd{help comma} or @kbd{help semicolon}. + +@defvr {Built-in Variable} 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"}. +@end defvr + +@defvr {Built-in Variable} 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. +@end defvr + +@defvr {Built-in Variable} suppress_verbose_help_message +If the value of @code{suppress_verbose_help_message} is nonzero, 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. +@end defvr + +@node Command Line Editing, Errors, Getting Help, Getting Started +@section Command Line Editing +@cindex command-line editing +@cindex editing the command line + +Octave uses the GNU readline library to provide an extensive set of +command-line editing and history features. Only the most common +features are described in this manual. Please see The GNU Readline +Library for more information. + +To insert printing characters (letters, digits, symbols, etc.), simply +type the character. Octave will insert the character at the cursor and +advance the cursor forward. + +Many of the command-line editing functions operate using control +characters. For example, the character @kbd{Control-a} moves the cursor +to the beginning of the line. To type @kbd{C-a}, hold down @key{CTRL} +and then press @key{a}. In the following sections, control characters +such as @kbd{Control-a} are written as @kbd{C-a}. + +Another set of command-line editing functions use Meta characters. On +some terminals, you type @kbd{M-u} by holding down @key{META} and +pressing @key{u}. If your terminal does not have a @key{META} key, you +can still type Meta charcters using two-character sequences starting +with @kbd{ESC}. Thus, to enter @kbd{M-u}, you could type +@key{ESC}@key{u}. The @kbd{ESC} character sequences are also allowed on +terminals with real Meta keys. In the following sections, Meta +characters such as @kbd{Meta-u} are written as @kbd{M-u}. + +@menu +* Cursor Motion:: +* Killing and Yanking:: +* Commands For Text:: +* Commands For Completion:: +* Commands For History:: +* Customizing the Prompt:: +* Diary and Echo Commands:: +@end menu + +@node Cursor Motion, Killing and Yanking, Command Line Editing, Command Line Editing +@subsection Cursor Motion + +The following commands allow you to position the cursor. + +@table @kbd +@item C-b +Move back one character. + +@item C-f +Move forward one character. + +@item DEL +Delete the character to the left of the cursor. + +@item C-d +Delete the character underneath the cursor. + +@item M-f +Move forward a word. + +@item M-b +Move backward a word. + +@item C-a +Move to the start of the line. + +@item C-e +Move to the end of the line. + +@item C-l +Clear the screen, reprinting the current line at the top. + +@item C-_ +@itemx C-/ +Undo the last thing that you did. You can undo all the way back to an +empty line. + +@item 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 table + +The above table describes the most basic possible keystrokes that you need +in order to do editing of the input line. On most terminals, you can +also use the arrow keys in place of @kbd{C-f} and @kbd{C-b} to move +forward and backward. + +Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves +forward a word. It is a loose convention that control keystrokes +operate on characters while meta keystrokes operate on words. + +There is also a function available so that you can clear the screen from +within Octave programs. + +@cindex clearing the screen + +@deftypefn {Built-in Function} {} clc () +@deftypefnx {Built-in Function} {} home () +Clear the terminal screen and move the cursor to the upper left corner. +@end deftypefn + +@node Killing and Yanking, Commands For Text, Cursor Motion, Command Line Editing +@subsection Killing and Yanking + +@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 @kbd +@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 +@kbd{M-DEL} because the word boundaries differ. +@end table + +And, here is how to @dfn{yank} the text back into the line. Yanking +means to copy the most-recently-killed text from the kill buffer. + +@table @kbd +@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 @kbd{C-y} or @kbd{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 Commands For Text, Commands For Completion, Killing and Yanking, Command Line Editing +@subsection Commands For Changing Text + +The following commands can be used for entering characters that would +otherwise have a special meaning (e.g., @kbd{TAB}, @kbd{C-q}, etc.), or +for quickly correcting typing mistakes. + +@table @kbd +@item C-q +@itemx C-v +Add the next character that you type to the line verbatim. This is +how to insert things like @kbd{C-q} for example. + +@item M-TAB +Insert a tab character. + +@item C-t +Drag the character before the cursor forward over the character at the +cursor, also moving the cursor forward. If the cursor is at the end of +the line, then transpose the two characters before it. + +@item 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 M-u +Uppercase the characters following the cursor to the end of the current +(or following) word, moving the cursor to the end of the word. + +@item M-l +Lowecase the characters following the cursor to the end of the current +(or following) word, moving the cursor to the end of the word. + +@item M-c +Uppercase the character following the cursor (or the beginning of the +next word if the cursor is between words), moving the cursor to the end +of the word. +@end table + +@node Commands For Completion, Commands For History, Commands For Text, Command Line Editing +@subsection Letting Readline Type For You +@cindex command completion + +The following commands allow Octave to complete commands and file names +for you. + +@table @kbd +@item TAB +Attempt to do completion on the text before the cursor. Octave can +complete commands and variables. + +@item M-? +List the possible completions of the text before the cursor. +@end table + +@defvr {Built-in Variable} 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). +@end defvr + +@deftypefn {Built-in Function} {} completion_matches (@var{hint}) +Generate possible completions given @var{hint}. + +This function is provided for the benefit of programs like Emacs which +might be controlling Octave and handling user input. The current +command number is not incremented when this function is called. This is +a feature, not a bug. +@end deftypefn + +@node Commands For History, Customizing the Prompt, Commands For Completion, Command Line Editing +@subsection Commands For Manipulating The History +@cindex command history +@cindex input history +@cindex history of commands + +Octave normally keeps track of the commands you type so that you can +recall previous commands to edit or execute them again. When you exit +Octave, the most recent commands you have typed, up to the number +specified by the variable @code{history_size}, are saved in a file. +When Octave starts, it loads an initial list of commands from the file +named by the variable @code{history_file}. + +Here are the commands for simple browsing and searching the history +list. + +@table @kbd +@item LFD +@itemx RET +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 C-p +Move `up' through the history list. + +@item C-n +Move `down' through the history list. + +@item M-< +Move to the first line in the history. + +@item M-> +Move to the end of the input history, i.e., the line you are entering! + +@item C-r +Search backward starting at the current line and moving `up' through +the history as necessary. This is an incremental search. + +@item C-s +Search forward starting at the current line and moving `down' through +the the history as necessary. +@end table + +On most terminals, you can also use the arrow keys in place of @kbd{C-p} +and @kbd{C-n} to move through the history list. + +In addition to the keyboard commands for moving through the history +list, Octave provides three functions for viewing, editing, and +re-running chunks of commands from the history list. + +@deffn {Command} history options +If invoked with no arguments, @code{history} displays a list of commands +that you have executed. Valid options 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 @var{N} +Only display the most recent @var{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}. +@end deffn + +@deffn {Command} edit_history options +If invoked with no arguments, @code{edit_history} allows you to edit the +history list using the editor named by the variable @code{EDITOR}. The +commands to be edited are first copied to a temporary file. When you +exit the editor, Octave executes the commands that remain in the file. +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. +@end deffn + +@deffn {Command} run_history +Similar to @code{edit_history}, except that the editor is not invoked, +and the commands are simply executed as they appear in the history list. +@end deffn + +@defvr {Built-in Variable} 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"}. +@end defvr + +@defvr {Built-in Variable} 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}. +@end defvr + +@defvr {Built-in Variable} 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}. +@end defvr + +@defvr {Built-in Variable} 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}. +@end defvr + +@node Customizing the Prompt, Diary and Echo Commands, Commands For History, Command Line Editing +@subsection Customizing the Prompt +@cindex prompt customization +@cindex customizing the prompt + +The following variables are available for customizing the appearance of +the command-line prompts. 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 + +@defvr {Built-in Variable} PS1 +The primary prompt string. When executing interactively, Octave +displays the primary prompt @code{PS1} when it is ready to read a +command. + +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{Strings}. +@end defvr + +@defvr {Built-in Variable} 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. The default +value of @code{PS2} is @code{"> "}. +@end defvr + +@defvr {Built-in Variable} 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. The +default value of @code{PS4} is @code{"+ "}. @xref{Invoking Octave}, for +a description of @code{--echo-input}. +@end defvr + +@node Diary and Echo Commands, , Customizing the Prompt, Command Line Editing +@subsection Diary and Echo Commands +@cindex diary of commands and output +@cindex command and ouput logs +@cindex logging commands and output +@cindex echoing executing commands +@cindex command echoing + +Octave's diary feature allows you to keep a log of all or part of an +interactive session by recording the input you type and the output that +Octave produces in a separate file. + +@deffn {Command} diary options +Create a list of all commands @emph{and} the output they produce, mixed +together just as you see them on your terminal. Valid options are: + +@table @code +@item on +Start recording your session in a file called @file{diary} in your +current working directory. + +@item off +Stop recording your session in the diary file. + +@item @var{file} +Record your session in the file named @var{file}. +@end table + +Without any arguments, @code{diary} toggles the current diary state. +@end deffn + +Sometimes it is useful to see the commands in a function or script as +they are being evaluated. This can be especially helpful for debugging +some kinds of problems. + +@deffn {Command} echo options +Control whether commands are displayed as they are executed. Valid +options are: + +@table @code +@item on +Enable echoing of commands as they are executed in script files. + +@item off +Disable echoing of commands as they are executed in script files. + +@item on all +Enable echoing of commands as they are executed in script files and +functions. + +@item off all +Disable echoing of commands as they are executed in script files and +functions. +@end table + +@noindent +If invoked without any arguments, @code{echo} toggles the current echo +state. +@end deffn + +@defvr {Built-in Variable} echo_executing_commands +This variable is may also be used to control the echo state. It may be +the sum of the following values: + +@table @asis +@item 1 +Echo commands read from script files. + +@item 2 +Echo commands from functions. + +@item 4 +Echo commands read from command line. +@end table + +More than one state can be active at once. For example, a value of 3 is +equivalent to the command @kbd{echo on all}. + +The value of @code{echo_executing_commands} is set by the @kbd{echo} +command and the command line option @code{--echo-input}. +@end defvr + +@node Errors, Executable Octave Programs, Command Line Editing, Getting Started +@section How Octave Reports Errors +@cindex error messages +@cindex messages, error There are two classes of errors that Octave produces when it encounters input that it is unable to understand @@ -235,296 +981,137 @@ path your program took before the error occurred, and to correct the error before trying again. -@node Help, Command Line Editing, Errors, Basics -@section Help +@node Executable Octave Programs, Comments, Errors, Getting Started +@section Executable Octave Programs +@cindex executable scripts +@cindex scripts +@cindex self contained programs +@cindex program, self contained +@cindex @samp{#!} -@deffn {Command} 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. +Once you have learned Octave, you may want to write self-contained +Octave scripts, using the @samp{#!} script mechanism. You can do this +on GNU systems and 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.} -For example, the command +For example, you could create a text file named @file{hello}, containing +the following lines: @example -help help -@end example - -@noindent -prints a short message describing the @code{help} command, and - -@example -help -i help +@group +#! @value{OCTAVEHOME}/bin/octave -qf +# a sample Octave program +printf ("Hello, world!\n"); +@end group @end example @noindent -starts the GNU Info browser at this node in the on-line version of the -manual. -@end deffn - -The help command can give you information about operators, but not the -comma and semicolons that are used as command separators. To get help -for those, you must type @code{help comma} or @code{help semicolon}. - -@defvr {Built-in Variable} 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"}. -@end defvr - -@defvr {Built-in Variable} 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. -@end defvr - -@defvr {Built-in Variable} suppress_verbose_help_message -If the value of @code{suppress_verbose_help_message} is nonzero, 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. -@end defvr - -@node Command Line Editing, Command History Functions, Help, Basics -@section Command Line Editing - -@defvr {Built-in Variable} 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 +After making this file executable (with the @code{chmod} command), you +can simply type: @example -octave:13> PS1 = "\\u@@\\H> " +hello @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}. -@end defvr - -@defvr {Built-in Variable} 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{"> "}. -@end defvr - -@defvr {Built-in Variable} 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}. -@end defvr - -@defvr {Built-in Variable} 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). -@end defvr - -@node Command History Functions, , Command Line Editing, Basics -@section Command History Functions - -Octave provides three functions for viewing, editing, and re-running -chunks of commands from the history list. - -@deffn {Command} history options -If invoked with no arguments, @code{history} displays a list of commands -that you have executed. Valid options 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}. -@end deffn - -@deffn {Command} edit_history options -If invoked with no arguments, @code{edit_history} allows you to edit the -history list using the editor named by the variable @code{EDITOR}. The -commands to be edited are first copied to a temporary file. When you -exit the editor, Octave executes the commands that remain in the file. -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 +at the shell, and the system will arrange to run Octave as if you had +typed: @example -edit_history 13 +octave hello @end example -@noindent -extracts all the commands from the 13th through the last in the history -list. The command +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}. Note that some +operating systems may place a limit on the number of characters that are +recognized after @samp{#!}. + +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. + +If you invoke an executable Octave script with command line arguments, +the arguments are available in the built-in variable @code{argv}. +@xref{Command Line Options}. For example, the following program will +reproduce the command line that is used to execute it. @example -edit_history 13 169 +@group +#! @value{OCTAVEHOME}/bin/octave -qf +printf ("%s", program_name); +for i = 1:nargin + printf (" %s", argv(i,:)); +endfor +printf ("\n"); +@end group @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. -@end deffn - -@defvr {Built-in Variable} 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"}. -@end defvr - -@deffn {Command} run_history -Similar to @code{edit_history}, except that the editor is not invoked, -and the commands are simply executed as they appear in the history list. -@end deffn +@node Comments, , Executable Octave Programs, Getting Started +@section Comments in Octave Programs +@cindex @samp{#} +@cindex @samp{%} +@cindex comments +@cindex use of comments +@cindex documenting Octave programs +@cindex programs -@defvr {Built-in Variable} 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}. -@end defvr - -@defvr {Built-in Variable} 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}. -@end defvr +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. -@defvr {Built-in Variable} 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}. -@end defvr - -@deffn {Command} 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 +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}: @example -diary on +@group +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; + @dots{} +endfunction +@end group @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 +The @code{help} command (@pxref{Getting 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 @kbd{help f} produces the output @example -diary my-diary.txt -@end example +@group + usage: f (x, t) -@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 + This function defines the right hand + side functions for a set of nonlinear + differential equations. +@end group @end example -@noindent -Without any arguments, @code{diary} toggles the current diary state. -@end deffn - -@deffn {Command} echo options -Control whether commands are displayed as they are executed. Valid -options are: - -@table @code -@item on -Enable echoing of commands as they are executed in script files. - -@item off -Disable echoing of commands as they are executed in script files. +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. -@item on all -Enable echoing of commands as they are executed in script files and -functions. - -@item off all -Disable echoing of commands as they are executed in script files and -functions. -@end table - -@noindent -If invoked without any arguments, @code{echo} toggles the current echo -state. -@end deffn - -@defvr {Built-in Variable} echo_executing_commands -@end defvr
--- a/doc/interpreter/bugs.texi +++ b/doc/interpreter/bugs.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -6,8 +6,8 @@ @c in the Octave distribution, as well as in the Octave manual. @ifclear BUGSONLY -@node Trouble, Copying, Installation, Top -@appendix Known Causes of Trouble with Octave +@node Trouble, Installation, Tips, Top +@appendix Known Causes of Trouble @end ifclear @ifset BUGSONLY
--- a/doc/interpreter/control.texi +++ b/doc/interpreter/control.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/cp-idx.texi +++ b/doc/interpreter/cp-idx.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/diffeq.texi +++ b/doc/interpreter/diffeq.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -40,9 +40,16 @@ @noindent using Hindmarsh's ODE solver LSODE. -@deftypefn {Lodable Function} {} lsode (@var{fcn}, @var{x0}, @var{t_out}, @var{t_crit}) -The first argument is the name of the function to call to -compute the vector of right hand sides. It must have the form +@deftypefn {Lodable Function} {} lsode (@var{fcn}, @var{x0}, @var{t}, @var{t_crit}) +Return a matrix of @var{x} as a function of @var{t}, given the initial +state of the system @var{x0}. Each row in the result matrix corresponds +to one of the elements in the vector @var{t}. The first element of +@var{t} corresponds to the initial state @var{x0}, so that the first row +of the output is @var{x0}. + +The first argument, @var{fcn}, is a string that names the function to +call to compute the vector of right hand sides for the set of equations. +It must have the form @example @var{xdot} = f (@var{x}, @var{t}) @@ -51,52 +58,54 @@ @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. +@end deftypefn -Here is an example of solving a set of two differential equations using -@code{lsode}. The function +Here is an example of solving a set of three differential equations using +@code{lsode}. Given the function + +@cindex oregonator @example -function xdot = f (x, t) +@group +function xdot = f (x, t) + + xdot = zeros (3,1); - 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); + xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) \ + - 8.375e-06*x(1)^2); + xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27; + xdot(3) = 0.161*(x(1) - x(3)); endfunction +@end group @end example @noindent -is integrated with the command +and the initial condition @code{x0 = [ 4; 1.1; 4 ]}, the set of +equations can be integrated using the command @example -x = lsode ("f", [1; 2], (t = linspace (0, 50, 200)')); +@group +t = linspace (0, 500, 1000); + +y = lsode ("f", x0, t); +@end group @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 +If you try this, you will see that the value of the result changes +dramatically between @var{t} = 0 and 5, and again around @var{t} = 305. +A more efficient set of output points might be @example -plot (t, x) +@group +t = [0, logspace (-1, log10(303), 150), \ + logspace (log10(304), log10(500), 150)]; +@end group @end example -@end deftypefn @deftypefn {Lodable Function} {} lsode_options (@var{opt}, @var{val}) When called with two arguments, this function allows you set options @@ -108,7 +117,7 @@ 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. +more information about the inner workings of @code{lsode}. @node Differential-Algebraic Equations, , Ordinary Differential Equations, Differential Equations @section Differential-Algebraic Equations @@ -128,9 +137,17 @@ @end example @end ifinfo -@deftypefn {Loadable Function} {[@var{x}, @var{xdot}] =} dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t_out}, @var{t_crit}) -The first argument is the name of the function to call to -compute the vector of residuals. It must have the form +@deftypefn {Loadable Function} {[@var{x}, @var{xdot}] =} dassl (@var{fcn}, @var{x0}, @var{xdot0}, @var{t}, @var{t_crit}) +Return a matrix of states and their first derivaties with respect to +@var{t}. Each row in the result matrices correspond to one of the +elements in the vector @var{t}. The first element of @var{t} +corresponds to the initial state @var{x0} and derivative @var{xdot0}, so +that the first row of the output @var{x} is @var{x0} and the first row +of the output @var{xdot} is @var{xdot0}. + +The first argument, @var{fcn}, is a string that names the function to +call to compute the vector of residuals for the set of equations. +It must have the form @example @var{res} = f (@var{x}, @var{xdot}, @var{t})
--- a/doc/interpreter/emacs.texi +++ b/doc/interpreter/emacs.texi @@ -4,8 +4,8 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Emacs, Installation, Amusements, Top -@chapter Using Emacs With Octave +@node Emacs, Grammar, Installation, Top +@appendix 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.@: @@ -35,12 +35,12 @@ @end menu @node Installing the Emacs Octave Package, Using Octave Mode, Emacs, Emacs -@section Installing the Emacs Octave Package +@appendixsec Installing the Emacs Octave Package -The Emacs package @file{octave} consists of the three files -@file{octave-mod.el}, @file{octave-inf.el}, and @file{octave-hlp.el}. -These files, or better yet their byte-compiled versions, should be -somewhere in your Emacs load-path. +The Emacs package @file{octave} consists of @file{octave-mod.el}, +@file{octave-inf.el}, and @file{octave-hlp.el}. These files, or better +yet their byte-compiled versions, should be somewhere in your Emacs +load-path. If you have GNU Emacs with a version number at least as high as 19.35, you are all set up, because the package is respectively will be part of @@ -52,7 +52,7 @@ if you want. @node Using Octave Mode, Running Octave From Within Emacs, Installing the Emacs Octave Package, Emacs -@section Using Octave Mode +@appendixsec Using Octave Mode If you are lucky, your sysadmins have already arranged everything so that Emacs automatically goes into Octave mode whenever you visit an @@ -68,7 +68,7 @@ @lisp (autoload 'octave-mode "octave-mod" nil t) (setq auto-mode-alist - (cons '(\"\\\\.m$\" . octave-mode) auto-mode-alist)) + (cons '("\\.m$" . octave-mode) auto-mode-alist)) @end lisp @item @@ -272,7 +272,7 @@ @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 +considerations apply for using @kbd{M-RET} as @kbd{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!'' @@ -343,7 +343,7 @@ 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 +@appendixsec Running Octave From Within Emacs The package @file{octave} provides commands for running an inferior Octave process in a special Emacs buffer. Use @@ -454,17 +454,15 @@ @end quotation @node Using the Emacs Info Reader for Octave, , Running Octave From Within Emacs, Emacs -@section Using the Emacs Info Reader for Octave +@appendixsec 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}, +You can also have Octave's @kbd{help -i} command invoke the Emacs Info +reader. To do this, you'll need @file{gnuserv}, which can be retrieved +from any GNU Emacs Lisp Code Directory archive, e.g.@: +@url{ftp://ftp.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive}, in the @file{packages} subdirectory. The alpha version of an enhanced version of gnuserv is available at -@file{ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz}. +@url{ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz}. If @file{gnuserv} is installed, add the lines @lisp @@ -484,7 +482,7 @@ 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 +startup file @file{~/.emacs-octave} (or the file pointed to by the Emacs variable @code{inferior-octave-startup-file}). @c Local Variables:
--- a/doc/interpreter/expr.texi +++ b/doc/interpreter/expr.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Expressions, Statements, Basics, Top +@node Expressions, Evaluation, Variables, Top @chapter Expressions @cindex expressions @@ -18,15 +18,8 @@ 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:: @@ -35,672 +28,11 @@ * 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 -constants 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 -@group -105 -1.05e+2 -1050e-1 -@end group -@end example - -To specify complex constants, you can write an expression of the form - -@example -@group -3 + 4i -3.0 + 4.0i -0.3e1 + 40e-1i -@end group -@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 -@group -octave:13> 3 + 4 i - -parse error: - - 3 + 4 i - ^ -@end group -@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 -@group -"parrot" -'parrot' -@end group -@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 - -@iftex -@tex -$$ a = \left[ \matrix{ 1 & 2 \cr 3 & 4 } \right] $$ -@end tex -@end iftex -@ifinfo -@example -@group - - / \ - | 1 2 | - a = | | - | 3 4 | - \ / - -@end group -@end example -@end ifinfo - -Elements of a matrix may be arbitrary expressions, provided that the -dimensions all make sense when combining the various pieces. For -example, given the above matrix, the expression - -@example -[ a, a ] -@end example - -@noindent -produces the matrix - -@example -@group -ans = - - 1 2 1 2 - 3 4 3 4 -@end group -@end example - -@noindent -but the expression - -@example -[ a, 1 ] -@end example - -@noindent -produces the error - -@example -error: number of rows must match near line 13, column 6 -@end example - -@noindent -(assuming that this expression was entered as the first thing on line -13, of course). - -Inside the square brackets that delimit a matrix expression, Octave -looks at the surrounding context to determine whether spaces and newline -characters should be converted into element and row separators, or -simply ignored, so commands like - -@example -[ linspace (1, 2) ] -@end example - -@noindent -and - -@example -@group -a = [ 1 2 - 3 4 ] -@end group -@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 +@node Index Expressions, Calling Functions, Expressions, Expressions +@section Index Expressions -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"}. - -@defvr {Built-in Variable} 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 defvr - -When you type a matrix or the name of a variable whose value is a -matrix, Octave responds by printing the matrix in with neatly aligned -rows and columns. If the rows of the matrix are too large to fit on the -screen, Octave splits the matrix and displays a header before each -section to indicate which columns are being displayed. - -@noindent -You can use the following variables to control the format of the output. - -@defvr {Built-in Variable} output_max_field_width -This variable specifies the maximum width of a numeric output field. -The default value is 10. -@end defvr - -@defvr {Built-in Variable} output_precision -This variable specifies the minimum number of significant figures to -display for numeric output. The default value is 5. -@end defvr - -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}. - -@defvr {Built-in Variable} 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 nonzero, 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 -@group -octave:13> rand (2,10) -ans = - - Columns 1 through 6: - - 0.75883 0.93290 0.40064 0.43818 0.94958 0.16467 - 0.75697 0.51942 0.40031 0.61784 0.92309 0.40201 - - Columns 7 through 10: - - 0.90174 0.11854 0.72313 0.73326 - 0.44672 0.94303 0.56564 0.82150 -@end group -@end smallexample - -@noindent -The default value of @code{split_long_rows} is nonzero. -@end defvr - -@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 -@group -s * [](mxn) = [](mxn) * s = [](mxn) - - [](mxn) + [](mxn) = [](mxn) - - [](0xm) * M(mxn) = [](0xn) - - M(mxn) * [](nx0) = [](mx0) - - [](mx0) * [](0xn) = 0(mxn) -@end group -@end example - -By default, dimensions of the empty matrix are printed along with the -empty matrix symbol, @samp{[]}. For example: - -@example -@group -octave:13> zeros (3, 0) -ans = - -[](3x0) -@end group -@end example - -The built-in variable @code{print_empty_dimensions} controls this -behavior. - -@defvr {Built-in Variable} print_empty_dimensions -If the value of @code{print_empty_dimensions} is nonzero, 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 -@end defvr - -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}. - -Octave will normally issue a warning if it finds an empty matrix in the -list of elements that make up another matrix. You can use the variable -@code{empty_list_elements_ok} to suppress the warning or to treat it as -an error. - -@defvr {Built-in Variable} 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 -nonzero, 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"}. -@end defvr - -When Octave parses a matrix expression, it examines the elements of the -list to determine whether they are all constants. If they are, it -replaces the list with a single matrix constant. - -@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 expression 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 ]}, and the range - -@example -1 : 3 : 5 -@end example - -@noindent -defines the set of values @samp{[ 1 4 ]}. - -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 -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}). - -When Octave parses a range expression, it examines the elements of the -expression to determine whether they are all constants. If they are, it -replaces the range expression with a single range constant. - -@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 -@group -x -x15 -__foo_bar_baz__ -fucnrdthsucngtagdjb -@end group -@end example - -@noindent -However, names like @code{__foo_bar_baz__} that begin and end with two -underscores are understood to be reserved for internal use by Octave. -You should not use them in code you write, except to access Octave's -documented internal variables and built-in symbolic constants. - -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 do not have fixed types, so it is possible to first -store a numeric value in a variable and then to later use the same name -to hold a string value in the same program. 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 +@opindex ( +@opindex ) An @dfn{index expression} allows you to reference or extract selected elements of a matrix or vector. @@ -836,7 +168,7 @@ 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}. +desired result. @xref{Special Utility Matrices}. @defvr {Built-in Variable} prefer_column_vectors If @code{prefer_column_vectors} is nonzero, operations like @@ -915,205 +247,7 @@ particularly for large matrices because Octave does not have to repeatedly resize the result. -@node Data Structures, Calling Functions, Index Expressions, Expressions -@section Data Structures -@cindex structures -@cindex data structures - -Octave includes 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. For example, the three -expressions - -@example -@group -x.a = 1 -x.b = [1, 2; 3, 4] -x.c = "string" -@end group -@end example - -@noindent -create a structure with three elements. To print the value of the -structure, you can type its name, just as for any other variable: - -@example -@group -octave:2> x -x = -@{ - a = 1 - b = - - 1 2 - 3 4 - - c = string -@} -@end group -@end example - -@noindent -Note that Octave may print the elements in any order. - -Structures may be copied. - -@example -@group -octave:1> y = x -y = -@{ - a = 1 - b = - - 1 2 - 3 4 - - c = string -@} -@end group -@end example - -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 -@group -octave:1> x.b.d = 3 -x.b.d = 3 -octave:2> x.b -ans = -@{ - d = 3 -@} -octave:3> x -x = -@{ - a = 1 - b = - @{ - d = 3 - @} - - c = string -@} -@end group -@end example - -Note that when Octave prints the value of a structure that contains -other structures, only a few levels are displayed. For example, - -@example -@group -octave:1> a.b.c.d.e = 1; -octave:2> a -a = -@{ - b = - @{ - c = <structure> - @} -@} -@end group -@end example - -@noindent -This prevents long and confusing output from large deeply nested -structures. - -@defvr {Built-in Variable} struct_levels_to_print -You can tell Octave how many structure levels to display by setting the -built-in variable @code{struct_levels_to_print}. The default value is 2. -@end defvr - -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 -@group -octave:1> function y = f (x) -> y.re = real (x); -> y.im = imag (x); -> endfunction -@end group -@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 -@group -octave:2> f (rand (3) + rand (3) * I); -ans = -@{ - im = - - 0.26475 0.14828 - 0.18436 0.83669 - - re = - - 0.040239 0.242160 - 0.238081 0.402523 -@} -@end group -@end example - -Function return lists can include structure elements, and they may be -indexed like any other variable. For example, - -@example -@group -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 -@end group -@end example - -It is also possible to cycle through all the elements of a structure in -a loop, using a special form of the @code{for} statement -(@pxref{The for Statement}) - -The following functions are available to give you information about -structures. - -@deftypefn {Built-in Function} {} is_struct (@var{expr}) -Returns 1 if the value of the expression @var{expr} is a structure. -@end deftypefn - -@deftypefn {Built-in Function} {} struct_contains (@var{expr}, @var{name}) -This function returns 1 if the expression @var{expr} is a structure and it -includes an element named @var{name}. The first argument must be a -structure and the second must be a string. -@end deftypefn - -@deftypefn {Built-in Function} {} struct_elements (@var{expr}) -If the expression @var{expr} is a structure, this function returns a -list of strings naming the elements of the structure. It is an error to -call @code{struct_elements} with an argument that is not a structure. -@end deftypefn - -@node Calling Functions, Global Variables, Data Structures, Expressions +@node Calling Functions, Arithmetic Ops, Index Expressions, Expressions @section Calling Functions A @dfn{function} is a name for a particular calculation. Because it has @@ -1288,140 +422,7 @@ of Octave by allowing users to specify a maximum allowable recursion depth. -@cindex global variables -@cindex @code{global} statement -@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 -@group -global a -global b = 2 -global c = 3, d, e = 5 -@end group -@end example - -It is necessary declare a variable as global within a function body in -order to access it. For example, - -@example -@group -global x -function f () -x = 1; -endfunction -f () -@end group -@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 -@group -function f () - global x; - x = 1; -endfunction -@end group -@end example - -Passing a global variable in a function parameter list will -make a local copy and not modify the global value. For example, given -the function - -@example -@group -function f (x) - x = 0 -endfunction -@end group -@end example - -@noindent -and the definition of @samp{x} as a global variable at the top level, - -@example -global x = 13 -@end example - -@noindent -the expression - -@example -f (x) -@end example - -@noindent -will display the value of @samp{x} from inside the function as @samp{0}, -but the value of @samp{x} at the top level remains unchanged, because -the function works with a @emph{copy} of its argument. - -@defvr {Built-in Variable} warn_comma_in_global_decl -If the value of @code{warn_comma_in_global_decl} is nonzero, 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 nonzero. -@end defvr - -@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 -@group -all_va_args endwhile -break for -catch function -continue global -else gplot -elseif gsplot -end if -end_try_catch return -end_unwind_protect try -endfor unwind_protect -endfunction unwind_protect_cleanup -endif while -@end group -@end example - -The following command-like functions are also reserved, and may not be -used as variable or function names: - -@example -@group -casesen echo load show -cd edit_history ls type -chdir format more which -clear help run_history who -diary history save whos -dir hold set -@end group -@end example - -@node Arithmetic Ops, Comparison Ops, Keywords, Expressions +@node Arithmetic Ops, Comparison Ops, Calling Functions, Expressions @section Arithmetic Operators @cindex arithmetic operators @cindex operators, arithmetic @@ -1439,36 +440,22 @@ @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} +@opindex + 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} +@opindex .+ Element by element addition. This operator is equivalent to @code{+}. @item @var{x} - @var{y} +@opindex - Subtraction. If both operands are matrices, the number of rows and columns of both must agree. @@ -1476,14 +463,17 @@ Element by element subtraction. This operator is equivalent to @code{-}. @item @var{x} * @var{y} +@opindex * Matrix multiplication. The number of columns of @var{x} must agree with the number of rows of @var{y}. @item @var{x} .* @var{y} +@opindex .* Element by element multiplication. If both operands are matrices, the number of rows and columns must both agree. @item @var{x} / @var{y} +@opindex / Right division. This is conceptually equivalent to the expression @example @@ -1497,9 +487,11 @@ a minimum norm solution is computed. @item @var{x} ./ @var{y} +@opindex ./ Element by element right division. @item @var{x} \ @var{y} +@opindex \ Left division. This is conceptually equivalent to the expression @example @@ -1513,11 +505,14 @@ a minimum norm solution is computed. @item @var{x} .\ @var{y} +@opindex .\ Element by element left division. Each element of @var{y} is divided by each corresponding element of @var{x}. @item @var{x} ^ @var{y} @itemx @var{x} ** @var{y} +@opindex ** +@opindex ^ 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 @@ -1530,16 +525,21 @@ @item @var{x} .^ @var{y} @item @var{x} .** @var{y} +@opindex .** +@opindex .^ Element by element power operator. If both operands are matrices, the number of rows and columns must both agree. @item -@var{x} +@opindex - Negation. @item +@var{x} +@opindex + Unary plus. This operator has no effect on the operand. @item @var{x}' +@opindex ' 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 @@ -1549,6 +549,7 @@ @end example @item @var{x}.' +@opindex .' Transpose. @end table @@ -1599,15 +600,6 @@ @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}. @@ -1630,29 +622,37 @@ @table @code @item @var{x} < @var{y} +@opindex < True if @var{x} is less than @var{y}. @item @var{x} <= @var{y} +@opindex <= True if @var{x} is less than or equal to @var{y}. @item @var{x} == @var{y} +@opindex == True if @var{x} is equal to @var{y}. @item @var{x} >= @var{y} +@opindex >= True if @var{x} is greater than or equal to @var{y}. @item @var{x} > @var{y} +@opindex > True if @var{x} is greater than @var{y}. @item @var{x} != @var{y} @itemx @var{x} ~= @var{y} @itemx @var{x} <> @var{y} +@opindex != +@opindex ~= +@opindex <> True if @var{x} is not equal to @var{y}. @end table String comparisons may also be performed with the @code{strcmp} function, not with the comparison operators listed above. -@xref{String Functions}. +@xref{Strings}. @node Boolean Expressions, Assignment Ops, Comparison Ops, Expressions @section Boolean Expressions @@ -1677,11 +677,6 @@ @subsection Element-by-element Boolean Operators @cindex element-by-element evaluation -@opindex | -@opindex & -@opindex ~ -@opindex ! - An @dfn{element-by-element boolean expression} is a combination of comparison expressions using the boolean operators ``or'' (@samp{|}), ``and'' (@samp{&}), and ``not'' (@samp{!}), @@ -1705,15 +700,19 @@ @table @code @item @var{boolean1} & @var{boolean2} +@opindex & Elements of the result are true if both corresponding elements of @var{boolean1} and @var{boolean2} are true. @item @var{boolean1} | @var{boolean2} +@opindex | 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} +@opindex ~ +@opindex ! Each element of the result is true if the corresponding element of @var{boolean} is false. @end table @@ -1753,9 +752,6 @@ @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, @@ -1765,6 +761,7 @@ @table @code @item @var{boolean1} && @var{boolean2} +@opindex && 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 overall expression is 0. If it is @@ -1774,6 +771,7 @@ is 1. Otherwise, the result of the overall expression is 0. @item @var{boolean1} || @var{boolean2} +@opindex || 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 overall expression is 1. If it is @@ -1979,9 +977,6 @@ @cindex operators, increment @cindex operators, decrement -@opindex ++ -@opindex -- - @node Increment Ops, Operator Precedence, Assignment Ops, Expressions @section Increment Operators @@ -2008,20 +1003,24 @@ @table @code @item ++@var{x} +@opindex ++ 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} +@opindex @code{--} 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}++ +@opindex ++ 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}-- +@opindex @code{--} 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 @@ -2032,10 +1031,9 @@ 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 +@cindex operator precedence @dfn{Operator precedence} determines how operators are grouped, when different operators appear close by in one expression. For example,
--- a/doc/interpreter/extend.texi +++ b/doc/interpreter/extend.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/fn-idx.texi +++ b/doc/interpreter/fn-idx.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/func.texi +++ b/doc/interpreter/func.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 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 +@node Functions and Scripts, Error Handling, Statements, Top @chapter Functions and Script Files @cindex defining functions @cindex user-defined functions @@ -64,7 +64,7 @@ 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}. +stands for the alert character (ASCII 7). @xref{Strings}. Once this function is defined, you can ask Octave to evaluate it by typing the name of the function. @@ -222,30 +222,6 @@ were passed to Octave. @end defvr -@defvr {Automatic Variable} nargout -When a function is called, this local variable is automatically -initialized to the number of arguments expected to be returned. For -example, - -@example -f () -@end example - -@noindent -will result in @code{nargout} being set to 0 inside the function -@code{f} and - -@example -[s, t] = f () -@end example - -@noindent -will result in @code{nargout} being set to 2 inside the function -@code{f}. - -At the top level, @code{nargout} is undefined. -@end defvr - @defvr {Built-in Variable} silent_functions If the value of @code{silent_functions} is nonzero, internal output from a function is suppressed. Otherwise, the results of expressions @@ -359,7 +335,31 @@ @noindent provided that the built-in variable @code{define_all_return_values} is nonzero and the value of @code{default_return_value} is @samp{[]}. -@xref{Built-in Variables}. +@xref{Summary of Built-in Variables}. + +@defvr {Automatic Variable} nargout +When a function is called, this local variable is automatically +initialized to the number of arguments expected to be returned. For +example, + +@example +f () +@end example + +@noindent +will result in @code{nargout} being set to 0 inside the function +@code{f} and + +@example +[s, t] = f () +@end example + +@noindent +will result in @code{nargout} being set to 2 inside the function +@code{f}. + +At the top level, @code{nargout} is undefined. +@end defvr @defvr {Built-in Variable} default_return_value The value given to otherwise unitialized return values if @@ -374,6 +374,15 @@ default value is 0. @end defvr +@deftypefn {Function File} {} 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. +@end deftypefn + @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 @@ -406,7 +415,7 @@ @deftypefn {Built-in Function} {} va_start () Position 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 +to call @code{va_start} if you do not plan to cycle through the arguments more than once. This function may only be called inside functions that have been declared to accept a variable number of input arguments. @@ -447,7 +456,7 @@ @defvr {Keyword} all_va_args This keyword 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 +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. @end defvr @@ -487,7 +496,7 @@ @deftypefn {Built-in Function} {} vr_val (@var{val}) Each time this function is called, it places the value of its argument at the end of the list of values to return from the current function. -Once @code{vr_val()} has been called, there is no way to go back to the +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. This function may only be called within functions that have been declared to return an unspecified number of output arguments (by using the special @@ -643,7 +652,7 @@ @defvr {Built-in Variable} 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. +@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 @@ -755,7 +764,7 @@ 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 +perform the call to @code{eval} 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 @@ -764,7 +773,7 @@ @deftypefn {Built-in Function} {} source (@var{file}) Parse and execute the contents of @var{file}. This is equivalent to executing commands from a script file, but without requiring the file to -be name @var{file}.m. +be named @var{file}.m. @end deftypefn @node Dynamically Linked Functions, Organization of Functions, Script Files, Functions and Scripts @@ -781,8 +790,8 @@ facilities. Here is an example of how to write a C++ function that Octave can load, -with commentary. The source for this function is distributed with -Octave, in the file @file{examples/hello.cc}. +with commentary. The source for this function is included in the source +distributions of Octave, in the file @file{examples/hello.cc}. To use this file, your version of Octave must support dynamic linking. To find out if it does, type the command @@ -899,7 +908,7 @@ The @code{octave_value_list} class is a zero-based array of @code{octave_value} objects. The declaration for the @code{octave_value} class is in the file @code{pt-const.h}. The -@code{print()} method will send its output to @code{octave_stdout}, so +@code{print} method will send its output to @code{octave_stdout}, so it will also end up going through the pager. @example
deleted file mode 100644 --- a/doc/interpreter/gnuinfo.texi +++ /dev/null @@ -1,1130 +0,0 @@ -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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}. - -@smallexample ------Info: (dir)Top, 40 lines --Top------------------------------------ - ^^ ^ ^^^ ^^ - (file)Node #lines where -@end smallexample - -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: - -@smallexample ---zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z------------ -@end smallexample - -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: - -@smallexample ------Info: *Completions*, 7 lines --All-------------------------------- -@end smallexample - -@node Basic Windows -@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 -@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 -@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 -@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 -@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 -
--- a/doc/interpreter/gpl.texi +++ b/doc/interpreter/gpl.texi @@ -1,10 +1,10 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 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, Concept Index, Trouble, Top +@node Copying, Concept Index, Grammar, Top @appendix GNU GENERAL PUBLIC LICENSE @center Version 2, June 1991
deleted file mode 100644 --- a/doc/interpreter/hsuser.texi +++ /dev/null @@ -1,154 +0,0 @@ -@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 -@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 -@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 -@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 -@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 -@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
--- a/doc/interpreter/image.texi +++ b/doc/interpreter/image.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -11,7 +11,8 @@ manipulate images, however, so some of these functions may be useful even if you are not able to view the results. -@deftypefn {Function File} {} colormap +@deftypefn {Function File} {} colormap (@var{map}) +@deftypefnx {Function File} {} colormap ("default") Set the current colormap. @code{colormap (@var{map})} sets the current colormap to @var{map}. The @@ -26,37 +27,33 @@ @end deftypefn @deftypefn {Function File} {} 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. +Return a gray colormap with @var{n} entries corresponding to values from +0 to @var{n}. The argument @var{n} should be a scalar. If it is +omitted, 64 is assumed. @end deftypefn -@deftypefn {Function File} {} gray2ind +@deftypefn {Function File} {[@var{img}, @var{map}] =} gray2ind (@var{}) Convert a gray scale intensity image to an Octave indexed image. @end deftypefn -@deftypefn {Function File} {} 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. +@deftypefn {Function File} {} image (@var{x}, @var{zoom}) +Display 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. If @var{zoom} is omitted, a value of 4 is +assumed. @end deftypefn -@deftypefn {Function File} {} 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. +@deftypefn {Function File} {} imagesc (@var{x}, @var{zoom}) +Display a scaled version of the matrix @var{x} as a color image. The +matrix is scaled so that its entries are indices into the current +colormap. The scaled matrix is returned. If @var{zoom} is omitted, a +value of 4 is assumed. @end deftypefn -@deftypefn {Function File} {} imshow +@deftypefn {Function File} {} imshow (@var{x}, @var{map}) +@deftypefnx {Function File} {} imshow (@var{x}, @var{n}) +@deftypefnx {Function File} {} imshow (@var{i}, @var{n}) +@deftypefnx {Function File} {} imshow (@var{r}, @var{g}, @var{b}) Display images. @code{imshow (@var{x})} displays an indexed image using the current @@ -70,71 +67,57 @@ @code{imshow (@var{r}, @var{g}, @var{b})} displays an RGB image. @end deftypefn -@deftypefn {Function File} {} ind2gray +@deftypefn {Function File} {} ind2gray (@var{x}, @var{map}) Convert an Octave indexed image to a gray scale intensity image. +If @var{map} is omitted, the current colormap is used to determine the +intensities. +@end deftypefn -@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. +@deftypefn {Function File} {[@var{r}, @var{g}, @var{b}] =} ind2rgb (@var{x}, @var{map}) +Convert an indexed image to red, green, and blue color components. +If @var{map} is omitted, the current colormap is used for the conversion. @end deftypefn -@deftypefn {Function File} {} 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. +@deftypefn {Function File} {[@var{x}, @var{map}] =} loadimage (@var{file}) +Load an image file and it's associated color map from the specified +@var{file}. The image must be stored in Octave's image format. @end deftypefn -@deftypefn {Function File} {} 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. +@deftypefn {Function File} {} rgb2ntsc (@var{rgb}) +Image format conversion. @end deftypefn -@c @deftypefn {Function File} {} rgb2ntsc -@c @end deftypefn - -@c @c @deftypefn {Function File} {} ntsc2rgb -@c @end deftypefn +@deftypefn {Function File} {} ntsc2rgb (@var{yiq}) +Image format conversion. +@end deftypefn @deftypefn {Function File} {} ocean (@var{n}) Create color colormap. The argument @var{n} should be a scalar. If it is omitted, 64 is assumed. @end deftypefn -@deftypefn {Function File} {} rgb2ind +@deftypefn {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{r}, @var{g}, @var{b}) Convert and RGB image to an Octave indexed image. - -@code{[@var{x}, @var{map}] = rgb2ind (@var{r}, @var{g}, @var{b})} @end deftypefn -@deftypefn {Function File} {} saveimage -Save a matrix to disk in image format. +@deftypefn {Function File} {} saveimage (@var{file}, @var{x}, @var{fmt}, @var{map}) +Save the matrix @var{x} to @var{file} in image format @var{fmt}. Valid +values for @var{fmt} are -@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})}. +@table @code +@item "img" +Octave's image format. The current colormap is also saved in the file. -@code{saveimage (@var{file}, @var{x}, "ppm")} saves the image in ppm -format instead of the default Octave image format. +@item "ppm" +Portable pixmap 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.) +@item "ps" +PostScript format. Note that images saved in PostScript format can not +be read back into Octave with loadimage. +@end table -@code{saveimage (@var{file}, @var{x}, @var{fmt}, @var{map})} saves the -image along with the specified colormap in the specified format. +If the fourth argument is supplied, the specified colormap will also be +saved along with the image. 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
--- a/doc/interpreter/install.texi +++ b/doc/interpreter/install.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -6,7 +6,7 @@ @c in the Octave distribution, as well as in the Octave manual. @ifclear INSTALLONLY -@node Installation, Trouble, Emacs, Top +@node Installation, Emacs, Trouble, Top @appendix Installing Octave @end ifclear @@ -217,7 +217,8 @@ while compiling @file{sighandlers.cc}, you may need to edit some files in the gcc include subdirectory to add proper 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}. +@code{signal} function 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: @@ -234,10 +235,10 @@ @end example @noindent -to match the prototype declaration for @code{signal()}. This change -should also be made for the @code{SIG_DFL} and @code{SIG_ERR} symbols. -It may be necessary to change the definitions in @file{sys/signal.h} as -well. +to match the prototype declaration for the @code{signal} function. This +change should also be made for the @code{SIG_DFL} and @code{SIG_ERR} +symbols. It may be necessary to change the definitions in +@file{sys/signal.h} as well. The gcc fixincludes/fixproto script should probably fix these problems when gcc installs its modified set of header files, but I don't think
--- a/doc/interpreter/intro.texi +++ b/doc/interpreter/intro.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Introduction, Invoking Octave, Preface, Top +@node Introduction, Getting Started, Preface, Top @chapter A Brief Introduction to Octave @cindex introduction @@ -43,9 +43,9 @@ 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. +its name from the fact that you type it by holding down @key{CTRL} and +then pressing @key{c}. Doing this will normally return you to Octave's +prompt. @cindex exiting octave @cindex quitting octave @@ -309,12 +309,12 @@ 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. +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 @key{CTRL} and then pressing @key{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}. @@ -350,7 +350,7 @@ text of the printed manual from within Octave normally uses a separate 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{Help}. +Info is provided in this manual in @ref{Getting Help}. @node Conventions, , Simple Examples, Introduction @section Conventions @@ -460,12 +460,13 @@ Some examples signal errors. This normally displays an error message on your terminal. Error messages are shown on a line starting with -@samp{@error{}}. Note that @samp{@error{}} itself does not appear on -your terminal. +@code{error:}. @example +@group struct_elements ([1, 2; 3, 4]) -@error{} struct_elements: wrong type argument `matrix' +error: struct_elements: wrong type argument `matrix' +@end group @end example @node Format of Descriptions, , Error Messages, Conventions @@ -544,22 +545,25 @@ @table @asis @item Built-in Function +@cindex built-in function The function described is written in a language like C++, C, or Fortran, and is part of the compiled Octave binary. @item Loadable Function +@cindex loadable function The function described is written in a language like C++, C, or Fortran. On systems that support dynamic linking of user-supplied functions, it may be automatically linked while Octave is running, but only if it is needed. @xref{Dynamically Linked Functions}. @item Function File +@cindex function file The function described is defined using Octave commands stored in a text file. @xref{Function Files}. @end table @node A Sample Command Description, A Sample Variable Description, A Sample Function Description, Format of Descriptions -@subsubsection A Sample Function Description +@subsubsection A Sample Command Description @cindex command descriptions Command descriptions have a format similar to function descriptions, @@ -571,15 +575,9 @@ @deffn {Command} cd dir @deffnx {Command} chdir dir Change the current working directory to @var{dir}. 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. +@kbd{cd ~/octave} 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. @end deffn @node A Sample Variable Description, , A Sample Command Description, Format of Descriptions @@ -587,20 +585,22 @@ @cindex variable descriptions A @dfn{variable} is a name that can hold a value. Although any variable -can be set by the user, certain variables that exist specifically so -that users can change them are called @dfn{user options}. Ordinary -variables and user options are described using a format like that for -functions except that there are no arguments. +can be set by the user, @dfn{built-in variables} typically exist +specifically so that users can change them to alter the way Octave +behaves (built-in variables are also sometimes called @dfn{user +options}). Ordinary variables and built-in variables are described +using a format like that for functions except that there are no +arguments. -Here is a description of the imaginary user option +Here is a description of the imaginary built-in variable @code{do_what_i_mean_not_what_i_say}. -@defvr {User Option} do_what_i_mean_not_what_i_say +@defvr {Built-in Variable} do_what_i_mean_not_what_i_say If the value of this variable is nonzero, Octave will do what you actually wanted, even if you have typed a completely different and meaningless list of commands. @end defvr -Other variable descriptions have the same format, but `User Option' is -replaced by `Variable', for ordinary variables, or `Constant' for -symbolic constants whose values cannot be changed. +Other variable descriptions have the same format, but `Built-in +Variable' is replaced by `Variable', for ordinary variables, or +`Constant' for symbolic constants whose values cannot be changed.
--- a/doc/interpreter/invoke.texi +++ b/doc/interpreter/invoke.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Invoking Octave, Basics, Introduction, Top +@node Invoking Octave, Getting Started, Introduction, Top @chapter Invoking Octave Normally, Octave is used interactively by running the program
--- a/doc/interpreter/io.texi +++ b/doc/interpreter/io.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Input and Output, Plotting, Built-in Variables, Top +@node Input and Output, Plotting, Error Handling, Top @chapter Input and Output There are two distinct classes of input and output functions. The first @@ -24,8 +24,8 @@ 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}. +used to force output to be sent to the pager (or any other stream) +immediately. 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 @@ -62,6 +62,13 @@ buffers its output and waits until just before the prompt is printed to flush it to the pager. The default value is 0. +@deftypefn {Built-in Function} {} fflush (@var{fid}) +Flush output to @var{fid}. 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}. +@end deftypefn + @c XXX FIXME XXX -- maybe this would be a good place to describe the @c following message: @c @@ -229,10 +236,10 @@ @node Terminal Input, Simple File I/O, Terminal Output, Basic Input and Output @subsection Terminal Input -Octave has two functions that make it easy to get input from the -terminal. The @code{input} function is normally used for managing an -interactive dialog with a user, and the @code{keyboard} function is -normally used for doing simple debugging. +Octave has three functions that make it easy to prompt users for +input. The @code{input} and @code{menu} functions are normally +used for managing an interactive dialog with a user, and the +@code{keyboard} function is normally used for doing simple debugging. @deftypefn {Built-in Function} {} input (@var{prompt}) @deftypefnx {Built-in Function} {} input (@var{prompt}, "s") @@ -265,7 +272,16 @@ 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}. +the screen before your prompt. @xref{Input and Output}. +@end deftypefn + +@deftypefn {Function File} {} 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. @end deftypefn @deftypefn {Built-in Function} {} keyboard (@var{prompt}) @@ -284,6 +300,25 @@ For both @code{input} and @code{keyboard}, the normal command line history and editing functions are available at the prompt. +Octave also has a function that makes it possible to get a single +character from the keyboard without requiring the user to type a +carriage return. + +@c XXX FIXME XXX -- perhaps kbhit should also be able to print a prompt +@c string? + +@deftypefn {Built-in Function} {} kbhit () +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 as soon as +it is typed. +@end deftypefn + @node Simple File I/O, , Terminal Input, Basic Input and Output @subsection Simple File I/O @@ -292,7 +327,7 @@ written by the @code{save} command can be controlled using the built-in variables @code{default_save_format} and @code{save_precision}. -Note that Octave can not save or load structure variables or any +Note that Octave can not yet save or load structure variables or any user-defined types. @deffn {Command} save options file v1 v2 @dots{} @@ -431,7 +466,6 @@ always use the symbolic names given in the table below, since it will make your programs easier to understand. - @defvr {Built-in Variable} stdin The standard input stream (file id 0). When Octave is used interactively, this is filtered through the command line editing @@ -451,6 +485,8 @@ @menu * Opening and Closing Files:: +* Simple Output:: +* Line-Oriented Input:: * Formatted Output:: * Output Conversion for Matrices:: * Output Conversion Syntax:: @@ -464,10 +500,12 @@ * Numeric Input Conversions:: * String Input Conversions:: * Binary I/O:: -* Other I/O Functions:: +* Temporary Files:: +* EOF and Errors:: +* File Positioning:: @end menu -@node Opening and Closing Files, Formatted Output, C-Style I/O Functions, C-Style I/O Functions +@node Opening and Closing Files, Simple Output, C-Style I/O Functions, C-Style I/O Functions @subsection Opening and Closing Files @deftypefn {Built-in Function} {[fid, msg] =} fopen (@var{name}, @var{mode}, @var{arch}) @@ -564,7 +602,45 @@ 0. Otherwise, it returns 1. @end deftypefn -@node Formatted Output, Output Conversion for Matrices, Opening and Closing Files, C-Style I/O Functions +@node Simple Output, Line-Oriented Input, Opening and Closing Files, C-Style I/O Functions +@subsection Simple Output + +@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string}) +Write a string to a file with no formatting. +@end deftypefn + +@deftypefn {Built-in Function} {} puts (@var{string}) +Write a string to the standard output with no formatting. +@end deftypefn + +@node Line-Oriented Input, Formatted Output, Simple Output, C-Style I/O Functions +@subsection Line-Oriented Input + +@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len}) +Read characters from a file, stopping at the first newline character +that is encountered or after @var{len} characters have been read, and +returning the characters as a string. The newline is not included in +the returned value. + +If @var{len} is omitted, @code{fgetl} reads until the next newline +character. + +If there are no more characters to read, @code{fgetl} returns -1. +@end deftypefn + +@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len}) +Read characters from a file, stopping at the first newline character +that is encountered or after @var{len} characters have been read, and +returning the characters as a string. The newline is included in the +returned value. + +If @var{len} is omitted, @code{fgets} reads until the next newline +character. + +If there are no more characters to read, @code{fgets} returns -1. +@end deftypefn + +@node Formatted Output, Output Conversion for Matrices, Line-Oriented Input, C-Style I/O Functions @subsection Formatted Output This section describes how to call @code{printf} and related functions. @@ -649,6 +725,37 @@ @node Output Conversion for Matrices, Output Conversion Syntax, Formatted Output, C-Style I/O Functions @subsection Output Conversion for Matrices +When given a matrix value, Octave's formatted output functions cycle +through the format template until all the values in the matrix have been +printed. For example, + +@example +@group +printf ("%4.2f %10.2e %8.4g\n", hilb (3)); + + @print{} 1.00 5.00e-01 0.3333 + @print{} 0.50 3.33e-01 0.25 + @print{} 0.33 2.50e-01 0.2 +@end group +@end example + +If more than one value is to be printed in a single call, the output +functions do not return to the beginning of the format template when +moving on from one value to the next. This can lead to confusing output +if the number of elements in the matrices are not exact multiples of the +number of conversions in the format template. For example, + +@example +@group +printf ("%4.2f %10.2e %8.4g\n", [1, 2], [3, 4]); + + @print{} 1.00 2.00e+00 3 + @print{} 4.00 +@end group +@end example + +If this is not what you want, use a series of calls instead of just one. + @node Output Conversion Syntax, Table of Output Conversions, Output Conversion for Matrices, C-Style I/O Functions @subsection Output Conversion Syntax @@ -1152,7 +1259,7 @@ 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 +@node Binary I/O, Temporary Files, String Input Conversions, C-Style I/O Functions @subsection Binary I/O Octave has to C-style functions for reading and writing binary data. @@ -1202,76 +1309,54 @@ are too large to fit in the specified precision. @end deftypefn -@node Other I/O Functions, , Binary I/O, C-Style I/O Functions -@subsection Other I/O Functions +@node Temporary Files, EOF and Errors, Binary I/O, C-Style I/O Functions +@subsection Temporary Files -@menu -* Miscellaneous Output Functions:: -* Miscellaneous Input Functions:: -* File Positioning Functions:: -* File Status Functions:: -* Subprocesses Communication:: -@end menu +@deftypefn {Built-in Function} {} tmpnam () +Return a unique temporary file name as a string. -@node Miscellaneous Output Functions, Miscellaneous Input Functions, Other I/O Functions, Other I/O Functions -@subsubsection Miscellaneous Output Functions - -@deftypefn {Built-in Function} {} fflush (@var{fid}) -Flush output to @var{fid}. 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}. +Since the named file is not opened, by @code{tmpnam}, it +is possible (though relatively unlikely) that it will not be available +by the time your program attempts to open it. @end deftypefn -@deftypefn {Built-in Function} {} fputs (@var{fid}, @var{string}) -Write a string to a file with no formatting. -@end deftypefn +@node EOF and Errors, File Positioning, Temporary Files, C-Style I/O Functions +@subsection End of File and Errors -@deftypefn {Built-in Function} {} puts (@var{string}) -Write a string to the standard output with no formatting. +@deftypefn {Built-in Function} {} feof (@var{fid}) +Returns 1 if an end-of-file condition has been encountered for a given +file and 0 otherwise. 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. @end deftypefn -@node Miscellaneous Input Functions, File Positioning Functions, Miscellaneous Output Functions, Other I/O Functions -@subsubsection Miscellaneous Input Functions - -@deftypefn {Built-in Function} {} fgetl (@var{fid}, @var{len}) -Read characters from a file, stopping at the first newline character -that is encountered or after @var{len} characters have been read, and -returning the characters as a string. The newline is not included in -the returned value. - -If @var{len} is omitted, @code{fgetl} reads until the next newline -character. - -If there are no more characters to read, @code{fgetl} returns -1. +@deftypefn {Built-in Function} {} ferror (@var{fid}) +Returns 1 if an error condition has been encountered for a given file +and 0 otherwise. 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. @end deftypefn -@deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len}) -Read characters from a file, stopping at the first newline character -that is encountered or after @var{len} characters have been read, and -returning the characters as a string. The newline is included in the -returned value. +@deftypefn {Built-in Function} {} freport () +Print a list of which files have been opened, and whether they are open +for reading, writing, or both. For example, + +@example +@group +freport () -If @var{len} is omitted, @code{fgets} reads until the next newline -character. - -If there are no more characters to read, @code{fgets} returns -1. + @print{} number mode name + @print{} + @print{} 0 r stdin + @print{} 1 w stdout + @print{} 2 w stderr + @print{} 3 r myfile +@end group +@end example @end deftypefn -@deftypefn {Built-in Function} {} kbhit () -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. -@end deftypefn - -@node File Positioning Functions, File Status Functions, Miscellaneous Input Functions, Other I/O Functions -@subsubsection File Positioning Functions +@node File Positioning, , EOF and Errors, C-Style I/O Functions +@subsection File Positioning Three functions are available for setting and determining the position of the file pointer for a given file. @@ -1315,55 +1400,3 @@ fseek (myfile, marker, SEEK_SET); @end example -@node File Status Functions, Subprocesses Communication, File Positioning Functions, Other I/O Functions -@subsubsection File Status Functions - -@deftypefn {Built-in Function} {} feof (@var{fid}) -Returns 1 if an end-of-file condition has been encountered for a given -file and 0 otherwise. 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. -@end deftypefn - -@deftypefn {Built-in Function} {} ferror (@var{fid}) -Returns 1 if an error condition has been encountered for a given file -and 0 otherwise. 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. -@end deftypefn - -@deftypefn {Built-in Function} {} 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 -freport () - - @print{} number mode name - @print{} - @print{} 0 r stdin - @print{} 1 w stdout - @print{} 2 w stderr - @print{} 3 r myfile -@end group -@end example -@end deftypefn - -@node Subprocesses Communication, , File Status Functions, Other I/O Functions -@subsubsection Communication with Subprocesses - -@deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) -Start a subprocess with 2-way communication. -@end deftypefn - -@deftypefn {Built-in Function} {fid =} popen (@var{command}, @var{mode}) -Open a pipe to a subprocess. -@end deftypefn - -@deftypefn {Built-in Function} {} pclose (@var{fid}) -Close a pipe from a subprocess. -@end deftypefn -
--- a/doc/interpreter/linalg.texi +++ b/doc/interpreter/linalg.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/matrix.texi +++ b/doc/interpreter/matrix.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Matrix Manipulation, Special Matrices, Plotting, Top +@node Matrix Manipulation, Arithmetic, Plotting, Top @chapter Matrix Manipulation There are a number of functions available for checking to see if the @@ -15,6 +15,8 @@ @menu * Finding Elements and Checking Conditions:: * Rearranging Matrices:: +* Special Utility Matrices:: +* Famous Matrices:: @end menu @node Finding Elements and Checking Conditions, Rearranging Matrices, Matrix Manipulation, Matrix Manipulation @@ -201,7 +203,7 @@ @end example @end deftypefn -@node Rearranging Matrices, , Finding Elements and Checking Conditions, Matrix Manipulation +@node Rearranging Matrices, Special Utility Matrices, Finding Elements and Checking Conditions, Matrix Manipulation @section Rearranging Matrices @deftypefn {Function File} {} fliplr (@var{x}) @@ -422,3 +424,391 @@ See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics. @end deftypefn + +@node Special Utility Matrices, Famous Matrices, Rearranging Matrices, Matrix Manipulation +@section Special Utility Matrices + +@deftypefn {Built-in Function} {} eye (@var{x}) +@deftypefnx {Built-in Function} {} eye (@var{n}, @var{m}) +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 vector with two elements, @code{eye} uses +the values of the elements as the number of rows and columns, +respecively. For example, + +@example +@group +eye (3) + + @result{} 1 0 0 + 0 1 0 + 0 0 1 +@end group +@end example + +The following expressions all produce the same result: + +@example +@group +eye (2) +@equiv{} +eye (2, 2) +@equiv{} +eye (size ([1, 2; 3, 4]) +@end group +@end example + +For compatibility with @sc{Matlab}, calling @code{eye} with no arguments +is equivalent to calling it with an argument of 1. +@end deftypefn + +@deftypefn {Built-in Function} {} ones (@var{x}) +@deftypefnx {Built-in Function} {} ones (@var{n}, @var{m}) +Returns a matrix whose elements are all 1. The arguments are handled +the same as the arguments for @code{eye}. + +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 +@end deftypefn + +@deftypefn {Built-in Function} {} zeros (@var{x}) +@deftypefnx {Built-in Function} {} zeros (@var{n}, @var{m}) +Returns a matrix whose elements are all 0. The arguments are handled +the same as the arguments for @code{eye}. +@end deftypefn + +@deftypefn {Loadable Function} {} rand (@var{x}) +@deftypefnx {Loadable Function} {} rand (@var{n}, @var{m}) +@deftypefnx {Loadable Function} {} rand (@code{"seed"}, @var{x}) +Returns a matrix with random elements uniformly distributed on the +interval (0, 1). The arguments are handled the same as the arguments +for @code{eye}. In +addition, you can set the seed for the random number generator using the +form + +@example +randn ("seed", @var{x}) +@end example + +@noindent +where @var{x} is a scalar value. If called as + +@example +rand ("seed") +@end example + +@noindent +@code{rand} returns the current value of the seed. +@end deftypefn + +@deftypefn {Loadable Function} {} randn (@var{x}) +@deftypefnx {Loadable Function} {} randn (@var{n}, @var{m}) +@deftypefnx {Loadable Function} {} randn (@code{"seed"}, @var{x}) +Returns a matrix with normally distributed random elements. The +arguments are handled the same as the arguments for @code{eye}. In +addition, you can set the seed for the random number generator using the +form + +@example +randn ("seed", @var{x}) +@end example + +@noindent +where @var{x} is a scalar value. If called as + +@example +randn ("seed") +@end example + +@noindent +@code{randn} returns the current value of the seed. +@end deftypefn + +The @code{rand} and @code{randn} functions use separate generators. +This ensures that + +@example +@group +rand ("seed", 13); +randn ("seed", 13); +u = rand (100, 1); +n = randn (100, 1); +@end group +@end example + +@noindent +and + +@example +@group +rand ("seed", 13); +randn ("seed", 13); +u = zeros (100, 1); +n = zeros (100, 1); +for i = 1:100 + u(i) = rand (); + n(i) = randn (); +end +@end group +@end example + +@noindent +produce equivalent results. + +Normally, @code{rand} and @code{randn} obtain their initial +seeds 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. + +If it is invoked without arguments, @code{rand} and @code{randn} return a +single element of a random sequence. + +The @code{rand} and @code{randn} functions use 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. + +@deftypefn {Built-in Function} {} diag (@var{v}, @var{k}) +Returns a diagonal matrix with vector @var{v} on diagonal @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 +@group +diag ([1, 2, 3], 1) + + @result{} 0 1 0 0 + 0 0 2 0 + 0 0 0 3 + 0 0 0 0 +@end group +@end example +@end deftypefn + +@c XXX FIXME XXX -- is this really worth documenting? +@c +@c @defvr {Built-in Variable} ok_to_lose_imaginary_part +@c If the value of @code{ok_to_lose_imaginary_part} is nonzero, implicit +@c conversions of complex numbers to real numbers are allowed (for example, +@c by fsolve). If the value is @code{"warn"}, the conversion is allowed, +@c but a warning is printed. Otherwise, an error message is printed and +@c control is returned to the top level. The default value is +@c @code{"warn"}. +@c +@c XXX FIXME XXX -- this is here because it is used by @code{ones}, +@c @code{zeros}, @code{rand}, etc. +@c @end defvr + +The functions @code{linspace} and @code{logspace} make it very easy to +create vectors with evenly or logarithmically spaced elements. +@xref{Ranges}. + +@deftypefn {Function File} {} linspace (@var{base}, @var{limit}, @var{n}) +creates a row vector with @var{n} (@var{n} greater than 1) 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 @code{linspace} function always returns a row vector, regardless of +the value of @code{prefer_column_vectors}. +@end deftypefn + +@deftypefn {Function File} {} logspace (@var{base}, @var{limit}, @var{n}) +Similar to @code{linspace} except that the values are logarithmically +spaced from +@iftex +@tex +$10^{base}$ to $10^{limit}$. +@end tex +@end iftex +@ifinfo +10^base to 10^limit. +@end ifinfo + +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. +@end deftypefn + +@defvr {Built-in Variable} treat_neg_dim_as_zero +If the value of @code{treat_neg_dim_as_zero} is nonzero, 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 0. +@end defvr + +@node Famous Matrices, , Special Utility Matrices, Matrix Manipulation +@section Famous Matrices + +The following functions return famous matrix forms. + +@deftypefn {Function File} {} hadamard (@var{k}) +Return the Hadamard matrix of order n = 2^k. +@end deftypefn + +@deftypefn {Function File} {} 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 +@end deftypefn + +@deftypefn {Function File} {} 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 +@end deftypefn + +@deftypefn {Function File} {} 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. +@end deftypefn + +@deftypefn {Function File} {} 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 +@end deftypefn + +@deftypefn {Function File} {} 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 deftypefn
--- a/doc/interpreter/nonlin.texi +++ b/doc/interpreter/nonlin.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -1,4 +1,4 @@ -% Copyright (C) 1996 John W. Eaton +% Copyright (C) 1996, 1997 John W. Eaton % This is part of the Octave manual. % For copying conditions, see the file gpl.texi. @@ -16,9 +16,7 @@ @c Settings for printing on 8-1/2 by 11 inch paper: @c ----------------------------------------------- -@c @ignore @setchapternewpage odd -@c @end ignore @c Settings for small book format: @c ------------------------------ @@ -44,7 +42,7 @@ @ifinfo -Copyright (C) 1996 John W. Eaton. +Copyright (C) 1996, 1997 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -70,15 +68,15 @@ @titlepage @title{Octave} @subtitle{A high-level interactive language for numerical computations} -@subtitle{Edition 2 for Octave version @value{VERSION}} +@subtitle{Edition 3 for Octave version @value{VERSION}} @subtitle{October 1996} @author{John W. Eaton} @page @vskip 0pt plus 1filll -Copyright @copyright{} 1996 John W. Eaton. +Copyright @copyright{} 1996, 1997 John W. Eaton. -This is the second edition of the Octave documentation, -and is consistent with version @value{VERSION} of Octave. +This is the third 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 @@ -91,6 +89,11 @@ Permission is granted to copy and distribute translations of this manual into another language, under the same conditions as for modified versions. + +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. @end titlepage @ifinfo @@ -105,17 +108,20 @@ @menu * Preface:: * Introduction:: A brief introduction to Octave. -* Invoking Octave:: Command options supported by Octave. -* Basics:: +* Getting Started:: +* Data Types:: +* Numeric Data Types:: +* Strings:: +* Data Structures:: +* Variables:: * Expressions:: Expressions. +* Evaluation:: * Statements:: Looping and program flow control. * Functions and Scripts:: -* Built-in Variables:: Descriptions of all built-in variables. +* Error Handling:: * Input and Output:: * Plotting:: * Matrix Manipulation:: -* Special Matrices:: -* String Functions:: * Arithmetic:: * Linear Algebra:: * Nonlinear Equations:: @@ -130,19 +136,24 @@ * Image Processing:: * Audio Processing:: * System Utilities:: -* Programming Utilities:: -* Amusements:: +* Tips:: +* Trouble:: If you have trouble installing Octave. +* Installation:: How to configure, compile and install Octave. * Emacs:: -* Installation:: How to configure, compile and install Octave. -* Trouble:: If you have trouble installing Octave. +* Grammar:: * Copying:: The GNU General Public License. * 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. + --- The Detailed Node Listing --- - --- The Detailed Node Listing --- +Preface + +* Acknowlegements:: +* How You Can Contribute to Octave:: +* Distribution:: A Brief Introduction to Octave @@ -164,31 +175,71 @@ * A Sample Command Description:: * A Sample Variable Description:: +Getting Started + +* Invoking Octave:: +* Quitting Octave:: +* Getting Help:: +* Command Line Editing:: +* Errors:: +* Executable Octave Programs:: +* Comments:: + Invoking Octave * Command Line Options:: * Startup Files:: -Basics +Command Line Editing + +* Cursor Motion:: +* Killing and Yanking:: +* Commands For Text:: +* Commands For Completion:: +* Commands For History:: +* Customizing the Prompt:: +* Diary and Echo Commands:: + +Data Types + +* Built-in Data Types:: +* User-defined Data Types:: +* Object Sizes:: + +Built-in Data Types + +* Numeric Objects:: +* String Objects:: +* Data Structure Objects:: -* Comments:: -* Executable Octave Programs:: -* Errors:: -* Help:: -* Command Line Editing:: -* Command History Functions:: +Numeric Data Types + +* Matrices:: +* Ranges:: +* Predicates for Numeric Objects:: + +Matrices + +* Empty Matrices:: + +Strings + +* Creating Strings:: +* Searching and Replacing:: +* String Conversions:: +* Character Class Functions:: + +Variables + +* Global Variables:: +* Status of Variables:: +* Summary of Built-in Variables:: +* Defaults from the Environment:: Expressions -* Constant Expressions:: -* Matrices:: -* Ranges:: -* Variables:: * Index Expressions:: -* Data Structures:: * Calling Functions:: -* Global Variables:: -* Keywords:: * Arithmetic Ops:: * Comparison Ops:: * Boolean Expressions:: @@ -196,15 +247,6 @@ * Increment Ops:: * Operator Precedence:: -Constant Expressions - -* Numeric Constants:: -* String Constants:: - -Matrices - -* Empty Matrices:: - Calling Functions * Call by Value:: @@ -242,11 +284,6 @@ * Dynamically Linked Functions:: * Organization of Functions:: -Built-in Variables - -* Miscellaneous Built-in Variables:: -* Summary of Preference Variables:: - Input and Output * Basic Input and Output:: @@ -261,6 +298,8 @@ C-Style I/O Functions * Opening and Closing Files:: +* Simple Output:: +* Line-Oriented Input:: * Formatted Output:: * Output Conversion for Matrices:: * Output Conversion Syntax:: @@ -274,15 +313,9 @@ * Numeric Input Conversions:: * String Input Conversions:: * Binary I/O:: -* Other I/O Functions:: - -Other I/O Functions - -* Miscellaneous Output Functions:: -* Miscellaneous Input Functions:: -* File Positioning Functions:: -* File Status Functions:: -* Subprocesses Communication:: +* Temporary Files:: +* EOF and Errors:: +* File Positioning:: Plotting @@ -295,9 +328,6 @@ * Finding Elements and Checking Conditions:: * Rearranging Matrices:: - -Special Matrices - * Special Utility Matrices:: * Famous Matrices:: @@ -318,7 +348,7 @@ Quadrature -* Functions of one Variable:: +* Functions of One Variable:: * Orthogonal Collocation:: Differential Equations @@ -336,33 +366,21 @@ * Timing Utilities:: * Filesystem Utilities:: -* Interacting with the OS:: +* Controlling Subprocesses:: +* Process ID Information:: +* Environment Variables:: +* Current Working Directory:: * Password Database Functions:: * Group Database Functions:: * System Information:: -* Other Functions:: -Programming Utilities - -* Evaluating Strings as Commands:: -* Miscellaneous Utilities:: - -Using Emacs With Octave +Tips and Standards -* Installing the Emacs Octave Package:: -* Using Octave Mode:: -* Running Octave From Within Emacs:: -* Using the Emacs Info Reader for Octave:: - -Installing Octave - -* Installation Problems:: -* Binary Distributions:: - -Binary Distributions - -* Installing Octave from a Binary Distribution:: -* Creating a Binary Distribution:: +* Style Tips:: Writing clean and robust programs. +* Coding Tips:: Making code run faster. +* Documentation Tips:: Writing readable documentation strings. +* Comment Tips:: Conventions for writing comments. +* Function Headers:: Standard headers for functions. Known Causes of Trouble with Octave @@ -380,21 +398,45 @@ * 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. + +Installing Octave + +* Installation Problems:: +* Binary Distributions:: + +Binary Distributions + +* Installing Octave from a Binary Distribution:: +* Creating a Binary Distribution:: + +Using Emacs With Octave + +* Installing the Emacs Octave Package:: +* Using Octave Mode:: +* Running Octave From Within Emacs:: +* Using the Emacs Info Reader for Octave:: + +Grammar + +* Keywords:: @end menu @include preface.texi @include intro.texi -@include invoke.texi @include basics.texi +@include data.texi +@include numbers.texi +@include strings.texi +@include struct.texi +@include var.texi @include expr.texi +@include eval.texi @include stmt.texi @include func.texi -@include var.texi +@include errors.texi @include io.texi @include plot.texi @include matrix.texi -@include special.texi -@include strings.texi @include arith.texi @include linalg.texi @include nonlin.texi @@ -409,17 +451,22 @@ @include image.texi @include audio.texi @include system.texi -@include program.texi -@include amuse.texi + +@c maybe add again later, if anyone every writes any really interesting +@c fun stuff for Octave. +@c +@c @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 tips.texi +@include bugs.texi @include install.texi -@include bugs.texi +@include emacs.texi +@include grammar.texi @include gpl.texi @include cp-idx.texi
--- a/doc/interpreter/op-idx.texi +++ b/doc/interpreter/op-idx.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/optim.texi +++ b/doc/interpreter/optim.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -81,64 +81,105 @@ @node Linear Least Squares, , Nonlinear Programming, Optimization @section Linear Least Squares -@deftypefn {Function File} {} 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 +@deftypefn {Function File} {[@var{beta}, @var{v}, @var{r}] =} gls (@var{y}, @var{x}, @var{o}) +Generalized least squares estimation for the multivariate model -@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 +@iftex +@tex +$y = x b + e$ +with $\bar{e} = 0$ and cov(vec($e$)) = $(s^2)o$, +@end tex +@end iftex +@ifinfo +@code{@var{y} = @var{x} * @var{b} + @var{e}} with @code{mean (@var{e}) = +0} and @code{cov (vec (@var{e})) = (@var{s}^2)*@var{o}}, +@end ifinfo + where +@iftex +@tex +$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix, $b$ is a $k +\times p$ matrix, $e$ is a $t \times p$ matrix, and $o$ is a $tp \times +tp$ matrix. +@end tex +@end iftex +@ifinfo +@var{Y} is a @var{T} by @var{p} matrix, @var{X} is a @var{T} by @var{k} +matrix, @var{B} is a @var{k} by @var{p} matrix, @var{E} is a @var{T} by +@var{p} matrix, and @var{O} is a @var{T}@var{p} by @var{T}@var{p} +matrix. +@end ifinfo @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. +The return values @var{beta}, @var{v}, and @var{r} are defined as +follows. + +@table @var +@item beta +The GLS estimator for @var{b}. + +@item v +The GLS estimator for @code{@var{s}^2}. + +@item r +The matrix of GLS residuals, @code{@var{r} = @var{y} - @var{x} * +@var{beta}}. +@end table @end deftypefn -@deftypefn {Function File} {} ols (@var{Y}, @var{X}) -Ordinary Least Squares (OLS) estimation for the multivariate model +@deftypefn {Function File} {[@var{beta}, @var{sigma}, @var{r}] =} ols (@var{y}, @var{x}) +Ordinary least squares estimation for the multivariate model +@iftex +@tex +$y = x b + e$ +with +$\bar{e} = 0$, and cov(vec($e$)) = kron ($s, I$) +@end tex +@end iftex +@ifinfo +@code{@var{y} = @var{x}*@var{b} + @var{e}} with +@code{mean (@var{e}) = 0} and @code{cov (vec (@var{e})) = kron (@var{s}, +@var{I})}. +@end ifinfo + where +@iftex +@tex +$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix, +$b$ is a $k \times p$ matrix, and $e$ is a $t \times p$ matrix. +@end tex +@end iftex +@ifinfo @example -Y = X*B + E, mean (E) = 0, cov (vec (E)) = kron (S, I) +@var{y} is a @var{t} by @var{p} matrix, @var{X} is a @var{t} by @var{k} +matrix, @var{B} is a @var{k} by @var{p} matrix, and @var{e} is a @var{t} +by @var{p} matrix. @end example +@end ifinfo + +Each row of @var{y} and @var{x} is an observation and each column a +variable. -@noindent -with +The return values @var{beta}, @var{sigma}, and @var{r} are defined as +follows. + +@table @var +@item beta +The OLS estimator for @var{b}, @code{@var{beta} = pinv (@var{x}) * +@var{y}}, where @code{pinv (@var{x})} denotes the pseudoinverse of +@var{x}. + +@item sigma +The OLS estimator for the matrix @var{s}, @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 +@group +@var{sigma} = (@var{y}-@var{x}*@var{beta})' * (@var{y}-@var{x}*@var{beta}) / (@var{t}-rank(@var{x})) +@end group @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. +@item r +The matrix of OLS residuals, @code{@var{r} = @var{y} - @var{x} * @var{beta}}. +@end table @end deftypefn
--- a/doc/interpreter/plot.texi +++ b/doc/interpreter/plot.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -8,7 +8,7 @@ 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 +@code{gnuplot} functions @code{plot} and @code{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 @@ -101,17 +101,27 @@ the border of the plot. @end deffn -@deffn {Command} set options -@deffnx {Command} show options +@deffn {Command} gset options +@deffnx {Command} gshow options @deffnx {Command} replot options In addition to the basic plotting commands, the whole range of -@code{set} and @code{show} commands from @code{gnuplot} are available, +@code{gset} and @code{gshow} 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). +@findex set +@findex show +Note that in Octave 2.0, the @code{set} and @code{show} commands were +renamed to @code{gset} and @code{gshow} in order to allow for +compatibility with the @sc{Matlab} graphics and GUI commands in a future +version of Octave. (For now, the old @code{set} and @code{show} +commands do work, but they print an annoying warning message to try to +get people to switch to using @code{gset} and @code{gshow}.) + +The @code{gset} and @code{gshow} commands allow you to set and show +@code{gnuplot} parameters. For more information about the @code{gset} +and @code{gshow} commands, see the documentation for @code{set} and +@code{show} in 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 @@ -122,9 +132,9 @@ For example, @example -set term tek40 -set output "/dev/plotter" -set title "sine with lines and cosine with impulses" +gset term tek40 +gset output "/dev/plotter" +gset title "sine with lines and cosine with impulses" replot "sin (x) w l" @end example @@ -136,6 +146,10 @@ 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. + +@findex shg +The command @code{shg} is equivalent to executing @code{replot} without +any arguments. @end deffn @defvr {Built-in Variable} automatic_replot @@ -215,52 +229,52 @@ 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{-} +@table @samp +@item - Set lines plot style (default). -@item @samp{.} +@item . Set dots plot style. -@item @samp{@@} +@item @@ Set points plot style. -@item @samp{-@@} +@item -@@ Set linespoints plot style. -@item @samp{^} +@item ^ Set impulses plot style. -@item @samp{L} +@item L Set steps plot style. -@item @samp{#} +@item # Set boxes plot style. -@item @samp{~} +@item ~ Set errorbars plot style. -@item @samp{#~} +@item #~ Set boxerrorbars plot style. -@item @samp{n} +@item n Interpreted as the plot color if @var{n} is an integer in the range 1 to 6. -@item @samp{nm} +@item 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} +@item 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} +@item + +@itemx * +@itemx o +@itemx x Used in combination with the points or linespoints styles, set the point style. @end table @@ -285,15 +299,15 @@ @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{+}. +@samp{+}) and color 1 (red), @var{y2} with lines, @var{y3} with lines of +color 4 (magenta) and @var{y4} with points displayed as @samp{+}. @example plot (b, "*") @end example This command will plot the data in @var{b} will be plotted with points -displayed as @code{*}. +displayed as @samp{*}. @end deftypefn @deftypefn {Function File} {} hold @var{args} @@ -393,10 +407,10 @@ 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 +@kbd{gset 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 +expected to be sorted. For example, with @kbd{parametric} set, it makes sense to plot a matrix like @iftex @tex @@ -437,16 +451,6 @@ @code{meshdom}. @end deftypefn -@deftypefn {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@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 a mesh. The -rows of @var{xx} are copies of @var{x}, and the columns of @var{yy} are -copies of @var{y}. - -@code{[@var{xx}, @var{yy}] = meshgrid (@var{x})} is an abbreviation for -@code{[@var{xx}, @var{yy}] = meshgrid (@var{x}, @var{x})}. -@end deftypefn - @defvr {Built-in Variable} gnuplot_binary The name of the program invoked by the plot command. The default value is @code{"gnuplot"}. @xref{Installation}. @@ -460,6 +464,12 @@ configure got it wrong, or if you upgrade your gnuplot installation. @end defvr +@deftypefn {Function File} {} figure (@var{n}) +Set the current plot window to plot window @var{n}. This function +currently requires X11 and a version of gnuplot that supports multiple +frames. +@end deftypefn + @defvr {Built-in Variable} 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 @@ -477,13 +487,12 @@ @deftypefn {Function File} {} mplot (@var{x}, @var{y}) @deftypefnx {Function File} {} mplot (@var{x}, @var{y}, @var{fmt}) @deftypefnx {Function File} {} mplot (@var{x1}, @var{y1}, @var{x2}, @var{y2}) -This is a modified version of @code{plot()} to work with the multiplot -version of @code{gnuplot} to plot multiple plots per page. +This is a modified version of the @code{plot} function that works with +the multiplot version of @code{gnuplot} to plot multiple plots per page. This plot version automatically advances to the next subplot position after each set of arguments are processed. -See command @var{plot()} for the various options to this command -as this is just mulitplot version of the same command. +See the description of the @var{plot} function for the various options. @end deftypefn @deftypefn {Function File} {} multiplot (@var{xn}, @var{yn}) @@ -499,6 +508,35 @@ If in multiplot mode, switches to single plot mode. @end deftypefn +@deftypefn {Function File} {} plot_border (...) +Multiple arguments allowed to specify the sides on which the border +is shown. Allowed arguments include: + +@table @code +@item "blank" +No borders displayed. + +@item "all" +All borders displayed + +@item "north" +North Border + +@item "south" +South Border + +@item "east" +East Border + +@item "west" +West Border +@end table + +@noindent +The arguments may be abbreviated to single characters. Without any +arguments, @code{plot_border} turns borders off. +@end deftypefn + @deftypefn {Function File} {} subplot (@var{rows}, @var{cols}, @var{index}) @deftypefnx {Function File} {} subplot (@var{rcn}) Sets @code{gnuplot} in multiplot mode and plots in location @@ -527,26 +565,35 @@ For example, a plot with 4 by 2 grid will have plot indices running as follows: -@example +@iftex +@tex +\vskip 10pt +\hfil\vbox{\offinterlineskip\hrule +\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr +height13pt&1&2&3&4\cr height12pt&&&&\cr\noalign{\hrule} +height13pt&5&6&7&8\cr height12pt&&&&\cr\noalign{\hrule}}} +\hfil +\vskip 10pt +@end tex +@end iftex +@ifinfo +@display @group - +-------+-------+-------+-------+ - | | | | | - | 1 | 2 | 3 | 4 | - | | | | | - +-------+-------+-------+-------+ - | | | | | - | 5 | 6 | 7 | 8 | - | | | | | - +-------+-------+-------+-------+ ++-----+-----+-----+-----+ +| 1 | 2 | 3 | 4 | ++-----+-----+-----+-----+ +| 5 | 6 | 7 | 8 | ++-----+-----+-----+-----+ @end group -@end example +@end display +@end ifinfo @end deftypefn @deftypefn {Function File} {} subwindow (@var{xn}, @var{yn}) Sets the subwindow position in multiplot mode for the next plot. The multiplot mode has to be previously initialized using the -@code{multiplot()} command, otherwise this command just becomes an alias -to @var{multiplot()} +@code{multiplot} function, otherwise this command just becomes an alias +to @var{multiplot} @end deftypefn @deftypefn {Function File} {} top_title (@var{string}) @@ -554,25 +601,6 @@ Makes a title with text @var{string} at the top (bottom) of the plot. @end deftypefn -@deftypefn {Function File} {} plot_border (...) -Multiple arguments allowed to specify the sides on which the border -is shown. Allowed arguments include: - -@example -@group - "blank", "BLANK", "b", "B", @result{} No borders displayed - "all", "ALL", "a", "A", @result{} All borders displayed - "north", "NORTH", "n", "N", @result{} North Border - "south", "SOUTH", "s", "S", @result{} South Border - "east", "EAST", "e", "E", @result{} East Border - "west", "WEST", "w", "W", @result{} West Border -@end group -@end example - -@noindent -Without any arguments, turns borders off. -@end deftypefn - @node Miscellaneous Plotting Functions, , Multiple Plots on One Page, Plotting @section Miscellaneous Plotting Functions @@ -653,9 +681,9 @@ 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 +The commands @kbd{gplot clear}, @kbd{gsplot clear}, and @kbd{replot +clear} are equivalent to @code{clearplot}. (Previously, commands like +@kbd{gplot clear} would evaluate @code{clear} as an ordinary expression and clear all the visible variables.) @end deftypefn
--- a/doc/interpreter/poly.texi +++ b/doc/interpreter/poly.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -112,6 +112,22 @@ coefficients are given by vector @var{c}. @end deftypefn +@deftypefn {Function File} {} polyfit (@var{n}, @var{y}, @var{n}) +Returns the coefficients of a polynomial @var{p}(@var{x}) of degree +@var{n} that minimizes +@iftex +@tex +$$ +\sum_{i=1}^N (p(x_i) - y_i)^2 +$$ +@end tex +@end iftex +@ifinfo +@code{sumsq (p(x(i)) - y(i))}, +@end ifinfo + to best fit the data in the least squares sense. +@end deftypefn + @deftypefn {Function File} {} polyinteg (@var{c}) Returns the coefficients of the integral the polynomial whose coefficients are represented by the vector @var{c}.
--- a/doc/interpreter/preface.texi +++ b/doc/interpreter/preface.texi @@ -1,10 +1,9 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @node Preface, Introduction, Top, Top @unnumbered Preface -@cindex acknowledgements @cindex contributors @cindex history @@ -48,6 +47,16 @@ Octave more useful by writing and contributing additional functions for it, and by reporting any problems you may have. +@menu +* Acknowlegements:: +* How You Can Contribute to Octave:: +* Distribution:: +@end menu + +@node Acknowlegements, How You Can Contribute to Octave, Preface, Preface +@unnumberedsec Acknowlegements +@cindex acknowledgements + 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. @@ -188,10 +197,53 @@ 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. + +@node How You Can Contribute to Octave, Distribution, Acknowlegements, Preface +@unnumberedsec How You Can Contribute to Octave +@cindex contributing to Octave +@cindex funding Octave development + +There are a number of ways that you can contribute to help make Octave a +better system. Perhaps the most important way to contribute is to write +high-quality code for solving new problems, and to make your code freely +available for others to use. + +If you find Octave useful, consider providing additional funding to +continue its development. Even a modest amount of additional funding +could make a significant difference in the amount of time that is +available for development and support. + +If you cannot provide funding or contribute code, you can still help +make Octave better and more reliable by reporting any bugs you find and +by offering suggestions for ways to improve Octave. @xref{Trouble}, for +tips on how to write useful bug reports. + +@node Distribution, , How You Can Contribute to Octave, Preface +@unnumberedsec Distribution +@cindex distribution of Octave + +Octave is @dfn{free} software. This means that everyone is free to +use it and free to redistribute it on certain conditions. Octave is not +in the public domain. It is copyrighted and there are restrictions on +its distribution, but the restrictions are designed to ensure that +others will have the same freedom to use and redistribute Octave that +you have. The precise conditions can be found in the GNU General Public +License that comes with Octave and that also appears in @ref{Copying}. + +Octave is available on CD-ROM with various collections of other free +software, and from the Free Software Foundation. Ordering a copy of +Octave from the Free Software Foundation helps to fund the development +of more free software. For more information, write to + +@quotation +Free Software Foundation@* +59 Temple Place---Suite 330@* +Boston, MA 02111--1307@* +USA +@end quotation + +Octave is also available on the Internet from +@url{ftp://ftp.che.wisc.edu/pub/octave}, and additional information is +available from @url{http://www.che.wisc.edu/octave}.
deleted file mode 100644 --- a/doc/interpreter/program.texi +++ /dev/null @@ -1,447 +0,0 @@ -@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, System Utilities, 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 - -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. - -@deftypefn {Built-in Function} {} eval (@var{command}) -Parse the string @var{command} and evaluate 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 -@end deftypefn - -@deftypefn {Built-in Function} {} feval (@var{name}, @dots{}) -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. -@end deftypefn - -@cindex Fordyce, A. P. -@findex newtroot -Here is a simple-minded function using @code{feval} that finds the root -of a user-supplied function of one variable using Newton's method. - -@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. - -@deftypefn {Function File} {} columns (@var{a}) -Return the number of columns of @var{a}. -@end deftypefn - -@deftypefn {Function File} {} rows (@var{a}) -Return the number of rows of @var{a}. -@end deftypefn - -@deftypefn {Function File} {} length (@var{a}) -Return the number of rows of @var{a} or the number of columns of -@var{a}, whichever is larger. -@end deftypefn - -@deftypefn {Function File} {} 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. -@end deftypefn - -@deftypefn {Built-in Function} {} is_global (@var{a}) -Return 1 if @var{a} is globally visible. Otherwise, return 0. -@end deftypefn - -@deftypefn {Function File} {} is_matrix (@var{a}) -Return 1 if @var{a} is a matrix. Otherwise, return 0. -@end deftypefn - -@deftypefn {Function File} {} is_vector (@var{a}) -Return 1 if @var{a} is a vector. Otherwise, return 0. -@end deftypefn - -@deftypefn {Function File} {} is_scalar (@var{a}) -Return 1 if @var{a} is a scalar. Otherwise, return 0. -@end deftypefn - -@deftypefn {Function File} {} is_square (@var{x}) -If @var{x} is a square matrix, then return the dimension of @var{x}. -Otherwise, return 0. -@end deftypefn - -@deftypefn {Function File} {} 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. -@end deftypefn - -@deftypefn {Built-in Function} {} isstr (@var{a}) -Return 1 if @var{a} is a string. Otherwise, return 0. -@end deftypefn - -@deftypefn {Function File} {} 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. -@end deftypefn - -@deffn {Command} clear options pattern @dots{} -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. -@end deffn - -@deffn {Command} who options pattern @dots{} -@deffnx {Command} whos options pattern @dots{} -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. - -The command @code{whos} is equivalent to @code{who -long}. -@end deffn - -@deftypefn {Built-in Function} {} 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. -@end deftypefn - -@deftypefn {Built-in Function} {} error (@var{template}, @dots{}) -The @code{error} function formats the optional arguments under the -control of the template string @var{template} using the same rules as -the @code{printf} family of functions (@pxref{Formatted Output}). -The resulting message is prefixed by the string @samp{error: } and -printed on the @code{stderr} stream. - -Calling @code{error} also sets 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 or scripts. - -If the error message does not end with a new line character, Octave will -print a traceback of all the function calls leading to the error. For -example, given the following function definitions: - -@example -@group -function f () g () end -function g () h () end -function h () nargin == 1 || error ("nargin != 1"); end -@end group -@end example - -@noindent -calling the function @code{f()} will result in a list of messages that -can help you to quickly locate the exact location of the error: - -@example -@group -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 group -@end example - -If the error message ends in a new line character, Octave will print the -message but 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 -@group -function h () nargin == 1 || error ("nargin != 1\n"); end -f () -error: nargin != 1 -@end group -@end example -@end deftypefn - -@defvr {Built-in Variable} error_text -@end defvr - -@defvr {Built-in Variable} beep_on_error -If the value of @code{beep_on_error} is nonzero, Octave will try -to ring your terminal's bell before printing an error message. The -default value is 0. -@end defvr - -@deftypefn {Built-in Function} {} warning (@var{msg}) -Print the message @var{msg} prefixed by the string @samp{warning: }. -@end deftypefn - -@deftypefn {Built-in Function} {} 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. -@end deftypefn - -@deftypefn {Function File} {} 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. -@end deftypefn - -@deftypefn {Function File} {} 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. -@end deftypefn - -@deftypefn {Built-in Function} {} document (@var{symbol}, @var{text}) -Set the documentation string for @var{symbol} to @var{text}. -@end deftypefn - -@deftypefn {Built-in Function} {} 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 = "@value{OCTAVEHOME}/share/octave/2.0/m/general/nargchk.m" -@end example -@end deftypefn - -@deftypefn {Built-in Function} {} completion_matches (@var{hint}) -Generate possible completions given @var{hint}. - -This function is provided for the benefit of programs like Emacs which -might be controlling Octave and handling user input. The current -command number is not incremented when this function is called. This is -a feature, not a bug. -@end deftypefn - -@deftypefn {Function File} {} 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. -@end deftypefn - -@deftypefn {Built-in Function} {} 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. -@end deftypefn - -@deffn {Command} type options name @dots{} -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. -@end deffn - -@deffn {Command} which name @dots{} -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 deffn - -@deftypefn {Built-in Function} {} octave_config_info () -Return a structure containing configuration and installation -information. -@end deftypefn
--- a/doc/interpreter/quad.texi +++ b/doc/interpreter/quad.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -6,14 +6,14 @@ @chapter Quadrature @menu -* Functions of one Variable:: +* Functions of One Variable:: * Orthogonal Collocation:: @end menu -@node Functions of one Variable, Orthogonal Collocation, Quadrature, Quadrature -@section Functions of one Variable +@node Functions of One Variable, Orthogonal Collocation, Quadrature, Quadrature +@section Functions of One Variable -@deftypefn {Loadable Function} {[@var{v}, @var{ier}, @var{nfun}] =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing}) +@deftypefn {Loadable Function} {[@var{v}, @var{ier}, @var{nfun}, @var{err}] =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing}) Integrate a nonlinear function of one variable using Quadpack. The first argument is the name of the function to call to compute the value of the integrand. It must have the form @@ -37,6 +37,12 @@ The optional argument @var{sing} is a vector of values at which the integrand is known to be singular. + +The result of the integration is returned in @var{v} and @var{ier} +contains an integer error code (0 indicates a successful integration). +The value of @var{nfun} indicates how many function evaluations were +required, and @var{err} contains an estimate of the error in the +solution. @end deftypefn @deftypefn {Loadable Function} {} quad_options (@var{opt}, @var{val}) @@ -47,7 +53,64 @@ their current values are displayed. @end deftypefn -@node Orthogonal Collocation, , Functions of one Variable, Quadrature +Here is an example of using @code{quad} to integrate the function + +@iftex +@tex +$$ + f(x) = x \sin (1/x) \sqrt {|1 - x|} +$$ +from $x = 0$ to $x = 3$. +@end tex +@end iftex +@ifinfo +@example + @var{f}(@var{x}) = @var{x} * sin (1/@var{x}) * sqrt (abs (1 - @var{x})) +@end example + +@noindent +from @var{x} = 0 to @var{x} = 3. +@end ifinfo + +This is a fairly difficult integration (plot the function over the range +of integration to see why). + +The first step is to define the function: + +@example +@group +function y = f (x) + y = x .* sin (1 ./ x) .* sqrt (abs (1 - x)); +endfunction +@end group +@end example + +Note the use of the `dot' forms of the operators. This is not necessary +for the call to @code{quad}, but it makes it much easier to generate a +set of points for plotting. + +Then we simply call quad: + +@example +@group +[v, ier, nfun, err] = quad ("f", 0, 3) + + @result{} 1.9819 + + @result{} 1 + + @result{} 5061 + + @result{} 1.1522e-07 +@end group +@end example + +Although @code{quad} returns a nonzero value for @var{ier}, the result +is reasonably accurate (to understand what is happening, examine what +happens to the result if you move the lower bound to 0.1, then 0.01, +then 0.001, etc.). + +@node Orthogonal Collocation, , Functions of One Variable, Quadrature @section Orthogonal Collocation @deftypefn {Loadable Function} {[@var{r}, @var{A}, @var{B}, @var{q}] =} colloc (@var{n}, "left", "right")
deleted file mode 100644 --- a/doc/interpreter/rluser.texi +++ /dev/null @@ -1,565 +0,0 @@ -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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 -@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. -
--- a/doc/interpreter/set.texi +++ b/doc/interpreter/set.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/signal.texi +++ b/doc/interpreter/signal.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. @@ -20,7 +20,7 @@ is assumed. This corresponds to removing a linear trend. @end deftypefn -@deftypefn {Function} {} fft (@var{a} [, @var{n}]) +@deftypefn {Function} {} 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}. @@ -31,7 +31,7 @@ padded with zeros. @end deftypefn -@deftypefn {Loadable Function} {} ifft (@var{a} [, @var{n}]) +@deftypefn {Loadable Function} {} 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}. @@ -43,7 +43,7 @@ padded with zeros. @end deftypefn -@deftypefn {Loadable Function} {} fft2 (@var{a} [, @var{n} [, @var{m}]]) +@deftypefn {Loadable Function} {} 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 @@ -52,7 +52,7 @@ zeros. @end deftypefn -@deftypefn {Loadable Function} {} ifft2 (@var{a} [, @var{n} [, @var{m}]]) +@deftypefn {Loadable Function} {} 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 @@ -61,7 +61,7 @@ zeros. @end deftypefn -@deftypefn {Built-in Function} {} fftconv (@var{a}, @var{b}, @var{N}) +@deftypefn {Built-in Function} {} 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 @@ -69,15 +69,15 @@ 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. +the optional argument @var{n} is specified, an N-point FFT is used. @end deftypefn -@deftypefn {Function File} {} fftfilt (@var{b}, @var{x}, @var{N}) +@deftypefn {Function File} {} 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 +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. @end deftypefn @@ -173,12 +173,25 @@ all zeros. @end deftypefn -@deftypefn {Function File} {} freqz -Compute the frequency response of a filter. +@deftypefn {Function File} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a}, @var{n}, "whole") +Return the complex frequency response @var{h} of the rational IIR filter +whose numerator and denominator coefficients are @var{b} and @var{a}, +respectively. The response is evaluated at @var{n} angular frequencies +between 0 and +@ifinfo + 2*pi. +@end ifinfo +@iftex +@tex + $2\pi$. +@end tex +@end iftex -@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 +@noindent +The output value @var{w} is a vector of the frequencies. + +If the fourth argument is omitted, the response is evaluated at +frequencies between 0 and @ifinfo pi. @end ifinfo @@ -188,29 +201,13 @@ @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. +If @var{n} is omitted, a value of 512 is assumed. +If @var{a} is omitted, the denominator is assumed to be 1 (this +corresponds to a simple FIR filter). -@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 +For fastest computation, @var{n} should factor into a small number of +small primes. @end deftypefn @deftypefn {Function File} {} sinc (@var{x})
--- a/doc/interpreter/special.texi +++ b/doc/interpreter/special.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node Special Matrices, String Functions, Matrix Manipulation, Top +@node Special Matrices, Arithmetic, Matrix Manipulation, Top @chapter Special Matrices Octave provides a number of functions for creating special matrix forms. @@ -182,6 +182,18 @@ @end example @end deftypefn +@defvr {Built-in Variable} ok_to_lose_imaginary_part +If the value of @code{ok_to_lose_imaginary_part} is nonzero, 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"}. + +XXX FIXME XXX -- this is here because it is used by @code{ones}, +@code{zeros}, @code{rand}, etc. +@end defvr + The functions @code{linspace} and @code{logspace} make it very easy to create vectors with evenly or logarithmically spaced elements. @xref{Ranges}.
--- a/doc/interpreter/stats.texi +++ b/doc/interpreter/stats.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/stmt.texi +++ b/doc/interpreter/stmt.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 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 +@node Statements, Functions and Scripts, Evaluation, Top @chapter Statements @cindex statements @@ -628,7 +628,8 @@ 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. +are evaluated. @xref{Error Handling}, for more information about the +@code{__error_text__} variable. Octave's @var{try} block is a very limited variation on the Lisp condition-case form (limited because it cannot handle different classes @@ -687,7 +688,7 @@ @example @group if (fine_dining_destination == on_a_boat - || fine_dining_destination == on_a_train + || fine_dining_destination == on_a_train) suess (i, will, not, eat, them, sam, i, am, i, will, not, eat, green, eggs, and, ham); endif
--- a/doc/interpreter/strings.texi +++ b/doc/interpreter/strings.texi @@ -1,18 +1,128 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. +@node Strings, Data Structures, Numeric Data Types, Top +@chapter Strings @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 +@group +"parrot" +'parrot' +@end group +@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. -@node String Functions, Arithmetic, Special Matrices, Top -@chapter String Functions +@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{'}. -@deftypefn {Function File} {} strcmp (@var{s1}, @var{s2}) -Compares two strings, returning 1 if they are the same, and 0 otherwise. +@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. -@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.} +@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. + +@menu +* Creating Strings:: +* Searching and Replacing:: +* String Conversions:: +* Character Class Functions:: +@end menu + +@node Creating Strings, Searching and Replacing, Strings, Strings +@section Creating Strings + +@deftypefn {Function File} {} blanks (@var{n}) +Returns a string of @var{n} blanks. @end deftypefn @deftypefn {Function File} {} int2str (@var{n}) @@ -35,78 +145,46 @@ @end example @end deftypefn -@defvr {Built-in Variable} implicit_str_to_num_ok -If the value of @code{implicit_str_to_num_ok} is nonzero, 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 0. -@end defvr - -@deftypefn {Built-in Function} {} undo_string_escapes (@var{s}) -Converts special characters in strings back to their escaped forms. For -example, the expression +@deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{}) +Return a string containing all the arguments contatenated. For example, @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, +@group +s = [ "ab"; "cde" ] +strcat (s, s, s) -@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. -@end deftypefn - -@deftypefn {Function File} {} bin2dec (@var{s}) -Given a binary number represented as a string of zeros and ones, -returns the corresponding decimal number. For example, - -@example -bin2dec ("1110") - @result{} 14 + @result{} ab ab ab + cdecdecde +@end group @end example @end deftypefn -@deftypefn {Function File} {} blanks (@var{n}) -Returns a string of @var{n} blanks. +@defvr {Built-in Variable} string_fill_char +@end defvr + +@deftypefn {Function File} {} 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 @end deftypefn +@deftypefn {Built-in Function} {} isstr (@var{a}) +Return 1 if @var{a} is a string. Otherwise, return 0. +@end deftypefn + +@node Searching and Replacing, String Conversions, Creating Strings, Strings +@section Searching and Replacing + @deftypefn {Function File} {} deblank (@var{s}) Removes the trailing blanks from the string @var{s}. @end deftypefn -@deftypefn {Function File} {} dec2bin (@var{n}) -Given a nonnegative integer, returns the corresponding binary number as -a string of ones and zeros. For example, - -@example -dec2bin (14) - @result{} "1110" -@end example -@end deftypefn - -@deftypefn {Function File} {} dec2hex (@var{n}) -Given a nonnegative integer, returns the corresponding hexadecimal -number as a string. For example, - -@example -dec2hex (2748) - @result{} "abc" -@end example -@end deftypefn - @deftypefn {Function File} {} 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. @@ -121,18 +199,6 @@ @end example @end deftypefn -@deftypefn {Function File} {} hex2dec (@var{s}) -Given a hexadecimal number represented as a string, returns the -corresponding decimal number. For example, - -@example -hex2dec ("12B") - @result{} 299 -hex2dec ("12b") - @result{} 299 -@end example -@end deftypefn - @deftypefn {Function File} {} 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, @@ -170,25 +236,14 @@ @end example @end deftypefn -@deftypefn {Function File} {} str2num (@var{s}) -Convert the string @var{s} to a number. -@end deftypefn - -@deftypefn {Function File} {} 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. +@deftypefn {Function File} {} strcmp (@var{s1}, @var{s2}) +Compares two strings, returning 1 if they are the same, and 0 otherwise. -@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 +@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.} @end deftypefn -@defvr {Built-in Variable} string_fill_char -@end defvr - @deftypefn {Function File} {} 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, @@ -215,6 +270,67 @@ @end quotation @end deftypefn +@node String Conversions, Character Class Functions, Searching and Replacing, Strings +@section String Conversions + +@deftypefn {Function File} {} bin2dec (@var{s}) +Given a binary number represented as a string of zeros and ones, +returns the corresponding decimal number. For example, + +@example +bin2dec ("1110") + @result{} 14 +@end example +@end deftypefn + +@deftypefn {Function File} {} dec2bin (@var{n}) +Given a nonnegative integer, returns the corresponding binary number as +a string of ones and zeros. For example, + +@example +dec2bin (14) + @result{} "1110" +@end example +@end deftypefn + +@deftypefn {Function File} {} dec2hex (@var{n}) +Given a nonnegative integer, returns the corresponding hexadecimal +number as a string. For example, + +@example +dec2hex (2748) + @result{} "abc" +@end example +@end deftypefn + +@deftypefn {Function File} {} hex2dec (@var{s}) +Given a hexadecimal number represented as a string, returns the +corresponding decimal number. For example, + +@example +hex2dec ("12B") + @result{} 299 +hex2dec ("12b") + @result{} 299 +@end example +@end deftypefn + +@deftypefn {Function File} {} str2num (@var{s}) +Convert the string @var{s} to a number. +@end deftypefn + +@deftypefn {Function File} {} toascii (@var{s}) +Return ASCII representation of @var{s} in a matrix. For example, + +@example +@group +toascii ("ASCII") + @result{} [ 65, 83, 67, 73, 73 ] +@end group + +@end example +@end deftypefn + @deftypefn {Function File} {} tolower (@var{s}) Return a copy of the string @var{s}, with each upper-case character replaced by the corresponding lower-case one; nonalphabetic characters @@ -239,17 +355,41 @@ @end example @end deftypefn -@deftypefn {Function File} {} toascii (@var{s}) -Return ASCII representation of @var{s} in a matrix. For example, +@deftypefn {Built-in Function} {} undo_string_escapes (@var{s}) +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 @code{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 -@group -toascii ("ASCII") - @result{} [ 65, 83, 67, 73, 73 ] -@end group +octave:13> undo_string_escapes (bell) +ans = \a +@end example + +@noindent +replaces the unprintable alert character with its printable +representation. +@end deftypefn -@end example -@end deftypefn +@defvr {Built-in Variable} implicit_str_to_num_ok +If the value of @code{implicit_str_to_num_ok} is nonzero, 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 0. +@end defvr + +@node Character Class Functions, , String Conversions, Strings +@section Character Class Functions Octave also provides the following C-type character class test functions. They all operate on string arrays and return matrices of
--- a/doc/interpreter/system.texi +++ b/doc/interpreter/system.texi @@ -1,8 +1,8 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. -@node System Utilities, Programming Utilities, Audio Processing, Top +@node System Utilities, Tips, Audio Processing, Top @chapter System Utilities This chapter describes the functions that are available to allow you to @@ -14,24 +14,22 @@ @menu * Timing Utilities:: * Filesystem Utilities:: -* Interacting with the OS:: +* Controlling Subprocesses:: +* Process ID Information:: +* Environment Variables:: +* Current Working Directory:: * Password Database Functions:: * Group Database Functions:: * System Information:: -* Other Functions:: @end menu @node Timing Utilities, Filesystem Utilities, System Utilities, System Utilities @section Timing Utilities -@deftypefn {Loadable Function} {} time () -Return 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. -@end deftypefn - -Several of Octave's time functions use a data structure for time that -includes the following elements: +Octave's core set of functions for manipulating time values are +patterned after the corresponding functions from the standard C library. +Several of these functions use a data structure for time that includes +the following elements: @table @code @item usec @@ -69,8 +67,26 @@ Time zone. @end table -@deftypefn {Loadable Function} {} mktime (@var{time_struct}) -Convert a time structure to the number of seconds since the epoch. +@noindent +In the descriptions of the following functions, this structure is +referred to as a @var{tm_struct}. + +@deftypefn {Loadable Function} {} time () +Return 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. +@end deftypefn + +@deftypefn {Function File} {} ctime (@var{t}) +Convert a value returned from @code{time} (or any other nonnegative +integer), to the local time and return a string of the same form as +@code{asctime}. The function @code{ctime (time)} is equivalent to +@code{asctime (localtime (time))}. +@end deftypefn + +@deftypefn {Loadable Function} {} gmtime (@var{t}) +Given a value returned from time (or any nonnegative integer), +return a time structure corresponding to CUT. @end deftypefn @deftypefn {Loadable Function} {} localtime (@var{t}) @@ -78,18 +94,17 @@ return a time structure corresponding to the local time zone. @end deftypefn -@deftypefn {Loadable Function} {} gmtime (@var{t}) -Given a value returned from time (or any nonnegative integer), -return a time structure corresponding to CUT. +@deftypefn {Loadable Function} {} mktime (@var{tm_struct}) +Convert a time structure to the number of seconds since the epoch. @end deftypefn -@deftypefn {Function File} {} asctime (@var{time_struct}) +@deftypefn {Function File} {} asctime (@var{tm_struct}) Convert a time structure to a string using the following five-field format: Thu Mar 28 08:40:14 1996. The function @code{ctime (time)} is equivalent to @code{asctime (localtime (time))}. @end deftypefn -@deftypefn {Loadable Function} {} strftime (@var{time_struct}) +@deftypefn {Loadable Function} {} strftime (@var{tm_struct}) Format a time structure in a flexible way using @samp{%} substitutions similar to those in @code{printf}. Except where noted, substituted fields have a fixed size; numeric fields are padded if necessary. @@ -231,6 +246,11 @@ @end table @end deftypefn +Most of the remaining functions described in this section are not +patterned after the standard C library. Some are available for +compatiblity with @sc{Matlab} and others are provided because they are +useful. + @deftypefn {Function File} {} clock () Return a vector containing the current year, month (1-12), day (1-31), hour (0-23), minute (0-59) and second (0-61). For example, @@ -328,50 +348,182 @@ coarse resolution.) @end deftypefn -@node Filesystem Utilities, Interacting with the OS, Timing Utilities, System Utilities +@deftypefn {Built-in Function} {} pause (@var{seconds}) +Suspend the execution of the 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 +@group +fprintf (stderr, "wait please...\n"); +pause (5); +clc; +@end group +@end example +@end deftypefn + +@deftypefn {Built-in Function} {} sleep (@var{seconds}) +Suspend the execution of the program. +@end deftypefn + +@deftypefn {Built-in Function} {} usleep (@var{microseconds}) +Suspend the execution of the program. +@end deftypefn + +@node Filesystem Utilities, Controlling Subprocesses, 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. -@deftypefn {Built-in Function} {} rename (@var{from}, @var{to}) -Rename a file. +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new}) +Change the name of file @var{old} to @var{new}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. @end deftypefn -@deftypefn {Built-in Function} {} unlink (@var{file}) -Delete a file. +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} unlink (@var{file}) +Delete @var{file}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. @end deftypefn -@deftypefn {Built-in Function} {} readdir (@var{dir}) -Returns names of files in the directory @var{dir} as an array of -strings. +@deftypefn {Built-in Function} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir}) +Return names of the files in the directory @var{dir} as an array of +strings. If an error occurs, return an empty matrix in @var{files}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. @end deftypefn -@deftypefn {Built-in Function} {} mkdir (@var{dir}) -Create a directory +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkdir (@var{dir}) +Create a directory named @var{dir}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. @end deftypefn -@deftypefn {Built-in Function} {} rmdir (@var{dir}) -Remove a directory. +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rmdir (@var{dir}) +Remove the directory named @var{dir}. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. +@end deftypefn + +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkfifo (@var{name}) +Create a FIFO special file. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. @end deftypefn @c XXX FIXME XXX -- this needs to be explained, but I don't feel up to @c it just now... @deftypefn {Built-in Function} {} umask (@var{mask}) -Set permission mask for file creation. +Set the permission mask for file creation. The parameter @var{mask} is +interpreted as an octal number. @end deftypefn -@deftypefn {Built-in Function} {} 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. -@end deftypefn +@deftypefn {Built-in Function} {[info, err, msg] =} stat (@var{file}) +@deftypefnx {Built-in Function} {[info, err, msg] =} lstat (@var{file}) +Return a structure @var{s} containing the following information about +@var{file}. + +@table @code +@item dev +ID of device containing a directory entry for this file. + +@item ino +File number of the file. + +@item modestr +File mode, as a string of ten letters or dashes as would be returned by +@kbd{ls -l}. + +@item nlink +Number of links. + +@item uid +User ID of file's owner. + +@item gid +Group ID of file's group. + +@item rdev +ID of device for block or character special files. + +@item size +Size in bytes. + +@item atime +Time of last access in the same form as time values returned from +@code{time}. @xref{Timing Utilities}. + +@item mtime +Time of last modification in the same form as time values returned from +@code{time}. @xref{Timing Utilities}. + +@item ctime +Time of last file status change in the same form as time values returned from +@code{time}. @xref{Timing Utilities}. -@deftypefn {Built-in Function} {} lstat (@var{file}) -Get information about a symbolic link. If @var{file} is not a symbolic -link, @code{lstat} is equivalent to @code{stat}. +@item blksize +Size of blocks in the file. + +@item blocks +Number of blocks allocated for file. +@end table + +If the call is successful @var{err} is 0 and @var{msg} is an empty +string. If the file does not exist, or some other error occurs, @var{s} +is an empty matrix, @var{err} is -1, and @var{msg} contains the +corresponding system error message. + +If @var{file} is a symbolic link, @code{stat} will return information +about the actual file the is referenced by the link. Use @code{lstat} +if you want information about the symbolic link itself. + +For example, + +@example +@group +[s, err, msg] = stat ("/vmlinuz") + + @result{} s = + @{ + atime = 855399756 + rdev = 0 + ctime = 847219094 + uid = 0 + size = 389218 + blksize = 4096 + mtime = 847219094 + gid = 6 + nlink = 1 + blocks = 768 + modestr = -rw-r--r-- + ino = 9316 + dev = 2049 + @} + + @result{} err = 0 + + @result{} msg = + +@end group +@end example @end deftypefn @deftypefn {Built-in Function} {} glob (@var{pattern}) @@ -387,117 +539,37 @@ filename pattern matching. @end deftypefn -@node Interacting with the OS, Password Database Functions, Filesystem Utilities, System Utilities -@section Interacting with the OS - -@deftypefn {Built-in Function} {} fork () -Create a copy of the current process. -@end deftypefn - -@deftypefn {Built-in Function} {} exec (@var{file}, @var{args}) -Replace current process with a new process. -@end deftypefn - -@deftypefn {Built-in Function} {fid =} dup2 (@var{old}, @var{new}) -Duplicate a file descriptor. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{file_ids}, @var{status}] =} pipe () -Create an interprocess channel. -@end deftypefn - -@deftypefn {Built-in Function} {} fcntl (@var{fid}, @var{request}, @var{argument}) -Control open file descriptors. +@deftypefn {Built-in Function} {} 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}. -@vtable @code -@item F_DUPFD -@item F_GETFD -@item F_GETFL -@item F_SETFD -@item F_SETFL -@item O_APPEND -@item O_CREAT -@item O_EXCL -@item O_NONBLOCK -@item O_RDONLY -@item O_RDWR -@item O_TRUNC -@item O_WRONLY -@end vtable -@end deftypefn +If the file cannot be found in the path, an empty matrix is returned. +For example, -@deftypefn {Built-in Function} {} getpgrp () -Return the process group id of the current process. -@end deftypefn - -@deftypefn {Built-in Function} {} getpid () -Return the process id of the current process. -@end deftypefn - -@deftypefn {Built-in Function} {} getppid () -Return the process id of the parent process. -@end deftypefn - -@deftypefn {Built-in Function} {} geteuid () -Return the effective user id of the current process. +@example +octave:13> file_in_path (LOADPATH, "nargchk.m") +ans = "@value{OCTAVEHOME}/share/octave/2.0/m/general/nargchk.m" +@end example @end deftypefn -@deftypefn {Built-in Function} {} getuid () -Return the real user id of the current process. -@end deftypefn - -@deftypefn {Built-in Function} {} getegid () -Return the effective group id of the current process. -@end deftypefn - -@deftypefn {Built-in Function} {} getgid () -Return the real group id of the current process. -@end deftypefn - -@deftypefn {Built-in Function} {} mkfifo -Create a FIFO special file. +@deftypefn {Built-in Function} {} tilde_expand (@var{string}) +Performs tilde expansion on @var{string}. @end deftypefn -@deftypefn {Built-in Function} {} waitpid (@var{pid}, @var{options}) -Wait for process @var{pid} to terminate. The @var{pid} argument can be: - -@table @asis -@item -1 -Wait for any child process. - -@item 0 -Wait for any child process whose process group ID is equal to that of -the Octave interpreter process. - -@item > 0 -Wait for termination of the child process with ID @var{PID}. -@end table - -The @var{options} argument can be: +@node Controlling Subprocesses, Process ID Information, Filesystem Utilities, System Utilities +@section Controlling Subprocesses -@table @asis -@item 0 -Wait until signal is received or a child process exits (this is the -default if the @var{options} argument is missing). - -@item 1 -Do not hang if status is not immediately available. - -@item 2 -Report the status of any child processes that are stopped, and whose -status has not yet been reported since they stopped. +Octave includes some high-level commands like @code{system} and +@code{popen} for starting subprocesses. If you want to run another +program to perform some task and then look at its output, you will +probably want to use these functions. -@item 3 -Implies both 1 and 2. -@end table - -If the return value is greater than 0, it is the process ID of the child -process that exited. If an error occurs, -1 is returned. -@end deftypefn - -@deftypefn {Built-in Function} {} atexit (@var{fcn}) -Register function to be called when Octave exits. -@end deftypefn +Octave also provides several very low-level Unix-like functions which +can also be used for starting subprocesses, but you should probably only +use them if you can't find any way to do what you need with the +higher-level functions. @deftypefn {Built-in Function} {} system (@var{string}, @var{return_output}, @var{type}) Execute a shell command specified by @var{string}. The second argument is optional. @@ -539,6 +611,18 @@ variable @code{status} to the integer @samp{2}. @end deftypefn +@deftypefn {Built-in Function} {fid =} popen (@var{command}, @var{mode}) +Open a pipe to a subprocess. +@end deftypefn + +@deftypefn {Built-in Function} {} pclose (@var{fid}) +Close a pipe from a subprocess. +@end deftypefn + +@deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) +Start a subprocess with 2-way communication. +@end deftypefn + @defvr {Built-in Variable} 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 @@ -562,6 +646,190 @@ your shell path. @end defvr +In most cases, the following functions simply decode their arguments and +make the corresponding Unix system calls. For a complete example of how +they can be used, look at the definition of the function @code{popen2}. + +@deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} fork () +Create a copy of the current process. + +Fork can return one of the following values: + +@table @asis +@item > 0 +You are in the parent process. The value returned from @code{fork} is +the process id of the child process. You should probably arrange to +wait for any child processes to exit. + +@item 0 +You are in the child process. You can call @code{exec} to start another +process. If that fails, you should probably call @code{exit}. + +@item < 0 +The call to @code{fork} failed for some reason. You must take evasive +action. A system dependent error message will be waiting in @var{msg}. +@end table +@end deftypefn + +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args}) +Replace current process with a new process. Calling @code{exec} without +first calling @code{fork} will terminate your current Octave process and +replace it with the program named by @var{file}. For example, + +@example +exec ("ls" "-l") +@end example + +@noindent +will run @code{ls} and return you to your shell prompt. + +If successful, @code{exec} does not return. If @code{exec} does return, +@var{err} will be nonzero, and @var{msg} will contain a system-dependent +error message. +@end deftypefn + +@deftypefn {Built-in Function} {[@var{file_ids}, @var{err}, @var{msg}] =} pipe () +Create a pipe and return the vector @var{file_ids}, which corresponding +to the reading and writing ends of the pipe. + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. +@end deftypefn + +@deftypefn {Built-in Function} {[fid, msg] =} dup2 (@var{old}, @var{new}) +Duplicate a file descriptor. + +If successful, @var{fid} is greater than zero and contains the new file +ID. Otherwise, @var{fid} is negative and @var{msg} contains a +system-dependent error message. +@end deftypefn + +@deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} waitpid (@var{pid}, @var{options}) +Wait for process @var{pid} to terminate. The @var{pid} argument can be: + +@table @asis +@item -1 +Wait for any child process. + +@item 0 +Wait for any child process whose process group ID is equal to that of +the Octave interpreter process. + +@item > 0 +Wait for termination of the child process with ID @var{PID}. +@end table + +The @var{options} argument can be: + +@table @asis +@item 0 +Wait until signal is received or a child process exits (this is the +default if the @var{options} argument is missing). + +@item 1 +Do not hang if status is not immediately available. + +@item 2 +Report the status of any child processes that are stopped, and whose +status has not yet been reported since they stopped. + +@item 3 +Implies both 1 and 2. +@end table + +If the returned value of @var{pid} is greater than 0, it is the process +ID of the child process that exited. If an error occurs, @var{pid} will +be less than zero and @var{msg} will contain a system-dependent error +message. +@end deftypefn + +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg}) +Change the properties of the open file @var{fid}. The following values +may be passed as @var{request}: + +@vtable @code +@item F_DUPFD +Return a duplicate file descriptor. + +@item F_GETFD +Return the file descriptor flags for @var{fid}. + +@item F_SETFD +Set the file descriptor flags for @var{fid}. + +@item F_GETFL +Return the file status flags for @var{fid}. The following codes may be +returned (some of the flags may be undefined on some systems). + +@vtable @code +@item O_RDONLY +Open for reading only. + +@item O_WRONLY +Open for writing only. + +@item O_RDWR +Open for reading and writing. + +@item O_APPEND +Append on each write. + +@item O_NONBLOCK +Nonblocking mode. + +@item O_SYNC +Wait for writes to complete. + +@item O_ASYNC +Asynchronous I/O. +@end vtable + +@item F_SETFL +Set the file status flags for @var{fid} to the value specified by +@var{arg}. The only flags that can be changed are @code{O_APPEND} and +@code{O_NONBLOCK}. +@end vtable + +If successful, @var{err} is 0 and @var{msg} is an empty string. +Otherwise, @var{err} is nonzero and @var{msg} contains a +system-dependent error message. +@end deftypefn + +@node Process ID Information, Environment Variables, Controlling Subprocesses, System Utilities +@section Process, Group, and User IDs + +@deftypefn {Built-in Function} {} getpgrp () +Return the process group id of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} getpid () +Return the process id of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} getppid () +Return the process id of the parent process. +@end deftypefn + +@deftypefn {Built-in Function} {} geteuid () +Return the effective user id of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} getuid () +Return the real user id of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} getegid () +Return the effective group id of the current process. +@end deftypefn + +@deftypefn {Built-in Function} {} getgid () +Return the real group id of the current process. +@end deftypefn + +@node Environment Variables, Current Working Directory, Process ID Information, System Utilities +@section Environemnt Variables + @deftypefn {Built-in Function} {} getenv (@var{var}) Returns the value of the environment variable @var{var}. For example, @@ -577,10 +845,8 @@ Set the value of the environment variable @var{var} to @var{value}. @end deftypefn -@deftypefn {Built-in Function} {} clc () -@deftypefnx {Built-in Function} {} home () -Clear the terminal screen and move the cursor to the upper left corner. -@end deftypefn +@node Current Working Directory, Password Database Functions, Environment Variables, System Utilities +@section Current Working Directory @deffn {Command} cd dir @deffnx {Command} chdir dir @@ -622,7 +888,7 @@ from system to system. @end deffn -@node Password Database Functions, Group Database Functions, Interacting with the OS, System Utilities +@node Password Database Functions, Group Database Functions, Current Working Directory, System Utilities @section Password Database Functions Octave's password database functions return information in a structure @@ -651,21 +917,22 @@ The initial shell. @end table -@deftypefn {Loadable Function} {passwd_struct =} getpwent () -Return an entry from the password database, opening it if necessary. -Once the end of the data has been reached, @code{getpwent} returns 0. +@deftypefn {Loadable Function} {} getpwent () +Return a structure containing an entry from the password database, +opening it if necessary. Once the end of the data has been reached, +@code{getpwent} returns 0. @end deftypefn -@deftypefn {Loadable Function} {passwd_struct =} getpwuid (@var{uid}). -Return the first entry from the password database with the user ID -@var{uid}. If the user ID does not exist in the database, -@code{getpwuid} returns 0. +@deftypefn {Loadable Function} {} getpwuid (@var{uid}). +Return a structure containing the first entry from the password database +with the user ID @var{uid}. If the user ID does not exist in the +database, @code{getpwuid} returns 0. @end deftypefn -@deftypefn {Loadable Function} {passwd_struct =} getpwnam (@var{name}) -Return the first entry from the password database with the user name -@var{name}. If the user name does not exist in the database, -@code{getpwname} returns 0. +@deftypefn {Loadable Function} {} getpwnam (@var{name}) +Return a structure containing the first entry from the password database +with the user name @var{name}. If the user name does not exist in the +database, @code{getpwname} returns 0. @end deftypefn @deftypefn {Loadable Function} {} setpwent () @@ -721,7 +988,7 @@ Close the group database. @end deftypefn -@node System Information, Other Functions, Group Database Functions, System Utilities +@node System Information, , Group Database Functions, System Utilities @section System Information @deftypefn {Built-in Function} {} computer () @@ -741,7 +1008,16 @@ @deftypefn {Built-in Function} {} 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}. +the built-in variable @code{OCTAVE_VERSION}. +@end deftypefn + +@defvr {Built-in Variable} OCTAVE_VERSION +The version number of Octave, as a string. +@end defvr + +@deftypefn {Built-in Function} {} octave_config_info () +Return a structure containing configuration and installation +information. @end deftypefn @deftypefn {Loadable Function} {} getrusage () @@ -805,48 +1081,3 @@ elements @code{sec} (seconds) @code{usec} (microseconds). @end table @end deftypefn - -@node Other Functions, , System Information, System Utilities -@section Other Functions - -@c XXX FIXME XXX -- need to define tilde expansion. - -@deftypefn {Built-in Function} {} tilde_expand (@var{string}) -Performs tilde expansion on @var{string}. -@end deftypefn - -@deftypefn {Built-in Function} {} pause (@var{seconds}) -Suspend the execution of the 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 -@group -fprintf (stderr, "wait please...\n"); -pause (5); -clc; -@end group -@end example -@end deftypefn - -@deftypefn {Built-in Function} {} sleep (@var{seconds}) -Suspend the execution of the program. -@end deftypefn - -@deftypefn {Built-in Function} {} usleep (@var{microseconds}) -Suspend the execution of the program. -@end deftypefn - -@c XXX FIXME XXX -- not really sure where these should go. - -@cindex exiting octave -@cindex quitting octave - -@deftypefn {Built-in Function} {} exit (@var{status}) -@deftypefnx {Built-in Function} {} quit (@var{status}) -Exit the current Octave session. If the optional integer value -@var{status} is supplied, pass that value to the operating system as the -Octave's exit status. -@end deftypefn
--- a/doc/interpreter/using.texi +++ b/doc/interpreter/using.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/interpreter/vr-idx.texi +++ b/doc/interpreter/vr-idx.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1996 John W. Eaton +@c Copyright (C) 1996, 1997 John W. Eaton @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi.
--- a/doc/texinfo.tex +++ b/doc/texinfo.tex @@ -1,7 +1,8 @@ -%% TeX macros to handle texinfo files +%% TeX macros to handle Texinfo files. +%% $Id: texinfo.tex,v 1.3 1997-02-13 18:33:50 jwe Exp $ % Copyright (C) 1985, 86, 88, 90, 91, 92, 93, -% 94, 95, 1996 Free Software Foundation, Inc. +% 94, 95, 96, 97 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 @@ -35,7 +36,7 @@ % This automatically updates the version number based on RCS. \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 1.2 $ +\deftexinfoversion$Revision: 1.3 $ \message{Loading texinfo package [Version \texinfoversion]:} % If in a .fmt file, print the version number @@ -59,7 +60,6 @@ \let\ptexrbrace=\} \let\ptexstar=\* \let\ptext=\t -\let\ptextilde=\~ % 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 @@ -72,7 +72,6 @@ \global\let\tiepenalty = \@M \gdef\tie{\leavevmode\penalty\tiepenalty\ } } -\let\~ = \tie % And make it available as @~. \message{Basics,} @@ -104,8 +103,8 @@ \hyphenation{eshell} % Margin to add to right of even pages, to left of odd pages. -\newdimen \bindingoffset -\newdimen \normaloffset +\newdimen \bindingoffset +\newdimen \normaloffset \newdimen\pagewidth \newdimen\pageheight % Sometimes it is convenient to have everything in the transcript file @@ -136,22 +135,39 @@ % %---------------------End change----------------------- +% Main output routine. +\chardef\PAGE = 255 +\output = {\onepageout{\pagecontents\PAGE}} + +\newbox\headlinebox \newbox\footlinebox + % \onepageout takes a vbox as an argument. Note that \pagecontents % does insertions, 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 + % + % Do this outside of the \shipout so @code etc. will be expanded in + % the headline as they should be, not taken literally (outputting ''code). + \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + % {% - \escapechar = `\\ % use backslash in output files. - \indexdummies + % Have to do this stuff outside the \shipout because we want it to + % take effect in \write's, yet the group defined by the \vbox ends + % before the \shipout runs. + % + \escapechar = `\\ % use backslash in output files. + \indexdummies % don't expand commands in the output. + \normalturnoffactive % \ in index entries must not stay \, e.g., if + % the page break happens to be in the middle of an example. \shipout\vbox{% - {\let\hsize=\pagewidth \makeheadline}% + \unvbox\headlinebox \pagebody{#1}% - {\let\hsize=\pagewidth \makefootline}% + \unvbox\footlinebox }% - }% + }% \advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi } @@ -850,7 +866,9 @@ % didn't need it. Make sure the catcode of space is correct to avoid % losing inside @example, for instance. % -\def\set{\begingroup\catcode` =10 \parsearg\setxxx} +\def\set{\begingroup\catcode` =10 + \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. + \parsearg\setxxx} \def\setxxx#1{\setyyy#1 \endsetyyy} \def\setyyy#1 #2\endsetyyy{% \def\temp{#2}% @@ -871,10 +889,16 @@ % @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} +\def\value{\begingroup + \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. + \valuexxx} +\def\valuexxx#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + {\{No value for ``#1''\}}% + \else + \csname SET#1\endcsname + \fi +\endgroup} % @ifset VAR ... @end ifset reads the `...' iff VAR has been defined % with @set. @@ -1289,16 +1313,21 @@ { \catcode`\-=\active \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} +% _ is always active; and it shouldn't be \let = to an _ that is a +% subscript character anyway. Then, @cindex @samp{_} (for example) +% fails. --karl +\global\def\indexbreaks{% + \catcode`\-=\active \let-\realdash +} } \def\realdash{-} -\def\realunder{_} \def\codedash{-\discretionary{}{}{}} \def\codeunder{\normalunderscore\discretionary{}{}{}} \def\codex #1{\tclose{#1}\endgroup} @@ -1318,7 +1347,7 @@ % Computer Modern typewriter fonts have zero interword stretch (and % shrink), and it is reasonable to expect all typewriter fonts to have % this property, we can check that font parameter. -% +% \def\ifmonospace{\ifdim\fontdimen3\font=0pt } % Typeset a dimension, e.g., `in' or `pt'. The only reason for the @@ -1879,7 +1908,7 @@ % To make preamble: % -% Either define widths of columns in terms of percent of \hsize: +% Either define widths of columns in terms of percent of \hsize: % @multitable @columnfractions .25 .3 .45 % @item ... % @@ -1897,13 +1926,13 @@ % the preamble, break the line within one argument and it % will parse correctly, i.e., % -% @multitable {Column 1 template} {Column 2 template} {Column 3 +% @multitable {Column 1 template} {Column 2 template} {Column 3 % template} % Not: -% @multitable {Column 1 template} {Column 2 template} +% @multitable {Column 1 template} {Column 2 template} % {Column 3 template} -% Each new table line starts with @item, each subsequent new 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. @@ -1915,15 +1944,15 @@ % @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 +% @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. % @end multitable @@ -1937,7 +1966,7 @@ % 0pt means it depends on current normal line spacing. %%%% -% Dimensions +% Dimensions \newskip\multitableparskip \newskip\multitableparindent @@ -2007,18 +2036,18 @@ % To parse everything between @multitable and @item : \setuptable#1 \endsetuptable % Need to reset this to 0 after \setuptable. -\global\colcount=0\relax% +\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 + % \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% \multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname % In order to keep entries from bumping into each other % we will add a \leftskip of \multitablecolspace to all columns after % the first one. - % If a template has been used, we will add \multitablecolspace + % If a template has been used, we will add \multitablecolspace % 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 @@ -2030,19 +2059,31 @@ \ifsetpercent \else % If user has <not> set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace + % we will advance \hsize by \multitablecolspace \advance\hsize by \multitablecolspace \fi % In either case we will make \leftskip=\multitablecolspace: \leftskip=\multitablecolspace \fi -\noindent##\multistrut}\cr% + % Ignoring space at the beginning and end avoids an occasional spurious + % blank line, when TeX decides to break the line at the space before the + % box from the multistrut, so the strut ends up on a line by itself. + % For example: + % @multitable @columnfractions .11 .89 + % @item @code{#} + % @tab Legal holiday which is valid in major parts of the whole country. + % Is automatically provided with highlighting sequences respectively marking + % characters. + \noindent\ignorespaces##\unskip\multistrut}\cr % \everycr will reset column counter, \colcount, at the end of - % each line. Every column entry will cause \colcount to advance by one. + % 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{% -\filbreak%% keeps underfull box messages off when table breaks over pages. +% \filbreak%% keeps underfull box messages off when table breaks over pages. +% Maybe so, but it also creates really weird page breaks when the table +% breaks over pages Wouldn't \vfil be better? Wait until the problem +% manifests itself, so it can be fixed for real --karl. \global\colcount=0\relax}} } @@ -2054,7 +2095,7 @@ %% to keep lines equally spaced \let\multistrut = \strut %% Test to see if parskip is larger than space between lines of -%% table. If not, do nothing. +%% table. If not, do nothing. %% If so, set to same dimension as multitablelinespace. \else \gdef\multistrut{\vrule height\multitablelinespace depth\dp0 @@ -2296,7 +2337,7 @@ \indexdummies % Must do this here, since \bf, etc expand at this stage \escapechar=`\\ {% - \let\folio=0 % We will expand all macros now EXCEPT \folio. + \let\folio=0% We will 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. % @@ -2570,7 +2611,7 @@ \endgroup % Back to normal single-column typesetting, but take account of the % fact that we just accumulated some stuff on the output page. - \pagegoal=\vsize + \pagegoal=\vsize } \def\balancecolumns{% % Called on the last page of the double column material. @@ -3096,7 +3137,7 @@ % Print any size section title. -% +% % #1 is the section type (sec/subsec/subsubsec), #2 is the section % number (maybe empty), #3 the text. \def\sectionheading#1#2#3{% @@ -3348,7 +3389,6 @@ \escapechar=`\\ % \let\,=\ptexcomma -\let\~=\ptextilde \let\{=\ptexlbrace \let\}=\ptexrbrace \let\.=\ptexdot @@ -3729,7 +3769,7 @@ % 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 % @@ -3763,17 +3803,16 @@ } % 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}}% +% braces (if any). That's what this does. +% +\def\removeemptybraces\empty#1\relax{#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}% + #1{\removeemptybraces#2\relax}{#3}% }% \def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % @@ -4007,19 +4046,21 @@ \def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} -% #1 is the data type. #2 is the name. +% #1 is the data type. #2 is the name, perhaps followed by text that +% is actually part of the data type, which should not be put into the index. \def\deftypevarheader #1#2{% -\doind {vr}{\code{#2}}% Make entry in variables index +\dovarind#2 \relax% Make entry in variables index \begingroup\defname {\defheaderxcond#1\relax$$$#2}{Variable}% \interlinepenalty=10000 \endgraf\penalty 10000\vskip -\parskip\penalty 10000 \endgroup} +\def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}} % @deftypevr {Global Flag} int enable \def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} -\def\deftypevrheader #1#2#3{\doind {vr}{\code{#3}}% +\def\deftypevrheader #1#2#3{\dovarind#3 \relax% \begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1} \interlinepenalty=10000 \endgraf\penalty 10000\vskip -\parskip\penalty 10000 @@ -4142,7 +4183,7 @@ % Use \turnoffactive so that punctuation chars such as underscore % work in node names. -\def\dosetq #1#2{{\let\folio=0 \turnoffactive \auxhat% +\def\dosetq #1#2{{\let\folio=0 \turnoffactive \edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% \next}} @@ -4211,84 +4252,101 @@ #2% Output the suffix in any case. } +% This is the macro invoked by entries in the aux file. +\def\xrdef #1#2{{% + \catcode`\'=\other + \expandafter\gdef\csname X#1\endcsname{#2}% +}} + % 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 +\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 + \catcode26=\other + \catcode`\^^[=\other + \catcode`\^^\=\other + \catcode`\^^]=\other + \catcode`\^^^=\other + \catcode`\^^_=\other + \catcode`\@=\other + \catcode`\^=\other + % It was suggested to define this as 7, which would allow ^^e4 etc. + % in xref tags, i.e., node names. But since ^^e4 notation isn't + % supported in the main text, it doesn't seem desirable. Furthermore, + % that is not enough: for node names that actually contain a ^ + % character, we would end up writing a line like this: 'xrdef {'hat + % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first + % argument, and \hat is not an expandable control sequence. It could + % all be worked out, but why? Either we support ^^ or we don't. + % + % The other change necessary for this was to define \auxhat: + % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter + % and then to call \auxhat in \setq. + % + \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. + \catcode43=\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 + % The aux file uses ' as the escape (for now). + % 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`\\=\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} @@ -4329,7 +4387,11 @@ % 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{% +% Oh yes, they do; otherwise, @ifset and anything else that uses +% \parseargline fail inside footnotes because the tokens are fixed when +% the footnote is read. --karl, 16nov96. +% +\long\gdef\footnotezzz{\insert\footins\bgroup % 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. @@ -4351,8 +4413,13 @@ % expands into a box, it must come within the paragraph, lest it % provide a place where TeX can split the footnote. \footstrut - #1\strut}% + \futurelet\next\fo@t } +\def\fo@t{\ifcat\bgroup\noexpand\next \let\next\f@@t + \else\let\next\f@t\fi \next} +\def\f@@t{\bgroup\aftergroup\@foot\let\next} +\def\f@t#1{#1\@foot} +\def\@foot{\strut\egroup} }%end \catcode `\@=11 @@ -4584,7 +4651,6 @@ \def~{{\tt \char '176}} \chardef\hat=`\^ \catcode`\^=\active -\def\auxhat{\def^{'hat}} \def^{{\tt \hat}} \catcode`\_=\active