@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2005, 2006,
@c               2007 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Getting Started
@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
* Invoking Octave from the Command Line::             
* Quitting Octave::             
* Getting Help::                
* Command Line Editing::        
* Errors::                      
* Executable Octave Programs::  
* Comments::                    
@end menu

@node Invoking Octave from the Command Line
@section Invoking Octave from the Command Line

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 @samp{octave --help} to display all
available options and briefly describe their use (@samp{octave -h} is a
shorter equivalent).

@menu
* Command Line Options::        
* Startup Files::               
@end menu

@node Command Line Options
@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.

@item --eval @var{code}
Evaluate @var{code} and exit when done unless @code{--persist} is also
specified.

@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
@code{OCTAVE_EXEC_PATH} found in the environment, but not any commands
in the system or user startup files that set the built-in variable
@code{EXEC_PATH}.

@item --help
@itemx -h
@itemx -?
@cindex @code{--help}
@cindex @code{-h}
@cindex @code{-?}
Print short help message and exit.

@item --image-path @var{path}
@cindex @code{--image-path @var{path}}
Specify the path to search for images.  The value of @var{path}
specified on the command line will set the value of
@code{IMAGE_PATH} found in the environment.

@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
@code{OCTAVE_INFO_FILE} found in the environment, but not any commands
in the system or user startup files that use the @code{info_file}
function.

@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
@code{OCTAVE_INFO_PROGRAM} found in the environment, but not any
commands in the system or user startup files that use the
@code{info_program} function.

@item --interactive
@itemx -i
@cindex @code{--interactive}
@cindex @code{-i}
Force interactive behavior.  This can be useful for running Octave via a
remote shell command or inside an Emacs shell buffer.  For another way
to run Octave within Emacs, see @ref{Emacs}.

@item --no-history
@itemx -H
Disable command-line history.

@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.

@item --no-site-file
@cindex @code{--no-site-file}
Don't read the site-wide @file{octaverc} file.

@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}.

@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
@code{OCTAVE_PATH} found in the environment, but not any commands in the
system or user startup files that set the internal load path through one
of the path functions.

@item --persist
Go to interactive mode after @code{--eval} or reading from a file
named on the command line.

@item --silent
@itemx --quiet
@itemx -q
@cindex @code{--silent}
@cindex @code{--quiet}
@cindex @code{-q}
Don't print the usual greeting and version message at startup.

@item --traditional
@itemx --braindead
@cindex @code{--traditional}
@cindex @code{--braindead}
For compatibility with @sc{Matlab}, set initial values for
user-preferences to the following values

@example
@group
PS1                     = ">> "
PS2                     = ""
beep_on_error           = true
crash_dumps_octave_core = false
default_save_options    = "-mat-binary"
fixed_point_format      = true
history_timestamp_format_string
                        = "%%-- %D %I:%M %p --%%"
page_screen_output      = false
print_empty_dimensions  = false
@end group
@end example

@noindent
and disable the following warnings
@example
@group
Octave:fopen-file-in-path
Octave:function-name-clash
Octave:load-file-in-path
@end group
@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}.  Exit when done unless
@code{--persist} is also specified.
@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.

@anchor{doc-argv}
@deftypefn {Built-in Function} {} argv ()
Return the command line arguments passed to Octave.  For example,
if you invoked Octave using the command

@example
octave --no-line-editing --silent
@end example

@noindent
@code{argv} would return a cell array of strings with the elements
@code{--no-line-editing} and @code{--silent}.

If you write an executable Octave script, @code{argv} will return the
list of arguments passed to the script.  @xref{Executable Octave Programs},
for an example of how to create an executable Octave script.
@end deftypefn


@anchor{doc-program_name}
@deftypefn {Built-in Function} {} program_name ()
Return the last component of of the value returned by
@code{program_invocation_name}.
@seealso{program_invocation_name}
@end deftypefn


@anchor{doc-program_invocation_name}
@deftypefn {Built-in Function} program_invocation_name ()
Return the name that was typed at the shell prompt to run Octave.

If executing a script from the command line (e.g., @code{octave foo.m})
or using an executable Octave script, the program name is set to the
name of the script.  @xref{Executable Octave Programs}, for an example of
how to create an executable Octave script.
@seealso{program_name}
@end deftypefn


Here is an example of using these functions to reproduce Octave's
command line.

@example
printf ("%s", program_name ());
arg_list = argv ();
for i = 1:nargin
  printf (" %s", arg_list@{i@});
endfor
printf ("\n");
@end example

@noindent
@xref{Index Expressions}, for an explanation of how to properly index
arrays of strings and substrings in Octave, and @xref{Defining Functions},
for information about the variable @code{nargin}.

@node Startup Files
@subsection Startup Files
@cindex initialization
@cindex startup

When Octave starts, it looks for commands to execute from the files in
the following list. These files may contain any valid Octave commands,
including function definitions.

@cindex startup files

@table @code
@item @var{octave-home}/share/octave/site/m/startup/octaverc
Where @var{octave-home} is the directory in which all of Octave is
installed (the default is @file{@value{OCTAVEHOME}}).  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 @var{octave-home}/share/octave/@var{version}/m/startup/octaverc
Where @var{octave-home} is the directory in which all of Octave is
installed (the default is @file{@value{OCTAVEHOME}}), and @var{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.

@node Quitting Octave
@section Quitting Octave
@cindex exiting octave
@cindex quitting octave

@anchor{doc-quit}
@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.  The default value is zero.
@end deftypefn


@anchor{doc-atexit}
@deftypefn {Built-in Function} {} atexit (@var{fcn})
Register a function to be called when Octave exits.  For example,

@example
@group
function bye_bye ()
  disp ("Bye bye");
endfunction
atexit ("bye_bye");
@end group
@end example

@noindent
will print the message "Bye bye" when Octave exits.

@deftypefnx {Built-in Function} {} atexit (@var{fcn}, @var{flag})
Register or unregister a function to be called when Octave exits,
depending on @var{flag}.  If @var{flag} is true, the function is
registered, if @var{flag} is false, it is unregistered.  For example,
after registering the function @code{bye_bye} as above,

@example
atexit ("bye_bye", false);
@end example

@noindent
will remove the function from the list and Octave will not call
the function @code{bye_by} when it exits.

Note that @code{atexit} only removes the first occurrence of a function
from the list, so if a function was placed in the list multiple
times with @code{atexit}, it must also be removed from the list
multiple times.
@end deftypefn


@node Getting Help
@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{doc}.  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.

@anchor{doc-help}
@deffn {Command} help @var{name}
Display the help text for @var{name}.
If invoked without any arguments, @code{help} prints a list
of all the available operators and functions.

For example, the command @kbd{help help} prints a short message
describing the @code{help} command.

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}.
@seealso{doc, which, lookfor}
@end deffn


@anchor{doc-doc}
@deftypefn {Command} doc @var{function_name}
Display documentation for the function @var{function_name}
directly from an on-line version of
the printed manual, using the GNU Info browser.  If invoked without
any arguments, the manual is shown from the beginning.

For example, the command @kbd{doc rand} starts the GNU Info browser
at this node in the on-line version of the manual.

Once the GNU Info browser is running, help for using it is available
using the command @kbd{C-h}.
@seealso{help}
@end deftypefn


@anchor{doc-lookfor}
@deffn {Command} lookfor @var{str}
@deffnx {Command} lookfor -all @var{str}
@deffnx {Function} {[@var{fun}, @var{helpstring}] = } lookfor (@var{str})
@deffnx {Function} {[@var{fun}, @var{helpstring}] = } lookfor ('-all', @var{str})
Search for the string @var{str} in all of the functions found in the
function search path.  By default @code{lookfor} searches for @var{str}
in the first sentence of the help string of each function found. The entire
help string of each function found in the path can be searched if
the '-all' argument is supplied. All searches are case insensitive.

Called with no output arguments, @code{lookfor} prints the list of matching
functions to the terminal. Otherwise the output arguments @var{fun} and
@var{helpstring} define the matching functions and the first sentence of
each of their help strings.

Note that the ability of @code{lookfor} to correctly identify the first
sentence of the help of the functions is dependent on the format of the
functions help. All of the functions in Octave itself will correctly
find the first sentence, but the same can not be guaranteed for other
functions. Therefore the use of the '-all' argument might be necessary
to find related functions that are not part of Octave.
@seealso{help, which}
@end deffn


The following function can be used to change which programs are used
for displaying the documentation, and where the documentation can be
found.

@anchor{doc-info_file}
@deftypefn {Built-in Function} {@var{val} =} info_file ()
@deftypefnx {Built-in Function} {@var{old_val} =} info_file (@var{new_val})
Query or set the internal variable that specifies the name of the
Octave info file.  The default value is
@code{"@var{octave-home}/info/octave.info"}, in
which @var{octave-home} is the directory where all of Octave is installed.
@seealso{info_program, doc, help, makeinfo_program}
@end deftypefn


@anchor{doc-info_program}
@deftypefn {Built-in Function} {@var{val} =} info_program ()
@deftypefnx {Built-in Function} {@var{old_val} =} info_program (@var{new_val})
Query or set the internal variable that specifies the name of the
info program to run.  The default value is
@code{"@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info"}
in which @var{octave-home} is the directory where all of Octave is
installed, @var{version} is the Octave version number, and @var{arch}
is the system type (for example, @code{i686-pc-linux-gnu}).  The
default initial value may be overridden by the environment variable
@code{OCTAVE_INFO_PROGRAM}, or the command line argument
@code{--info-program NAME}.
@seealso{info_file, doc, help, makeinfo_program}
@end deftypefn


@anchor{doc-makeinfo_program}
@deftypefn {Built-in Function} {@var{val} =} makeinfo_program ()
@deftypefnx {Built-in Function} {@var{old_val} =} makeinfo_program (@var{new_val})
Query or set the internal variable that specifies the name of the
makeinfo program that Octave runs to format help text containing
Texinfo markup commands.  The default initial value is @code{"makeinfo"}.
@seealso{info_file, info_program, doc, help}
@end deftypefn


@anchor{doc-suppress_verbose_help_message}
@deftypefn {Built-in Function} {@var{val} =} suppress_verbose_help_message ()
@deftypefnx {Built-in Function} {@var{old_val} =} suppress_verbose_help_message (@var{new_val})
Query or set the internal variable that controls whether Octave
will add additional help information to the end of the output from
the @code{help} command and usage messages for built-in commands.
@end deftypefn


@node Command Line Editing
@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 manual 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 characters 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 readline::        
* Customizing the Prompt::      
* Diary and Echo Commands::     
@end menu

@node Cursor Motion
@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 @key{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.

@cindex clearing the screen

The function @code{clc} will allow you to clear the screen from within
Octave programs.

@ifinfo
@anchor{doc-clc}
@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

@end ifinfo

@node Killing and Yanking
@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-@key{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-@key{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
@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-@key{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
Lowercase 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
@subsection Letting Readline Type For You
@cindex command completion

The following commands allow Octave to complete command and variable
names for you.

@table @kbd
@item @key{TAB}
Attempt to do completion on the text before the cursor.  Octave can
complete the names of commands and variables.

@item M-?
List the possible completions of the text before the cursor.
@end table

@anchor{doc-completion_append_char}
@deftypefn {Built-in Function} {@var{val} =} completion_append_char ()
@deftypefnx {Built-in Function} {@var{old_val} =} completion_append_char (@var{new_val})
Query or set the internal character variable that is appended to
successful command-line completion attempts.  The default
value is @code{" "} (a single space).
@end deftypefn


@anchor{doc-completion_matches}
@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
@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 @key{LFD}
@itemx @key{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 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.

@anchor{doc-history}
@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 @var{file}
Write the current history to the file @var{file}.  If the name is
omitted, use the default history file (normally @file{~/.octave_hist}).

@item -r @var{file}
Read the file @var{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
@kbd{history -q 5}.
@end deffn


@anchor{doc-edit_history}
@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


@anchor{doc-run_history}
@deffn {Command} run_history [first] [last]
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


Octave also allows you customize the details of how and where the history
is saved.

@anchor{doc-history_file}
@deftypefn {Built-in Function} {@var{val} =} history_file ()
@deftypefnx {Built-in Function} {@var{old_val} =} history_file (@var{new_val})
Query or set the internal variable that 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}.
@seealso{history_size, saving_history, history_timestamp_format_string}
@end deftypefn


@anchor{doc-history_size}
@deftypefn {Built-in Function} {@var{val} =} history_size ()
@deftypefnx {Built-in Function} {@var{old_val} =} history_size (@var{new_val})
Query or set the internal variable that 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}.
@seealso{history_file, history_timestamp_format, saving_history}
@end deftypefn


@anchor{doc-saving_history}
@deftypefn {Built-in Function} {@var{val} =} saving_history ()
@deftypefnx {Built-in Function} {@var{old_val} =} saving_history (@var{new_val})
Query or set the internal variable that controls whether commands entered
on the command line are saved in the history file.
@seealso{history_file, history_size, history_timestamp_format}
@end deftypefn


@anchor{doc-history_timestamp_format_string}
@deftypefn {Built-in Function} {@var{val} =} history_timestamp_format_string ()
@deftypefnx {Built-in Function} {@var{old_val} =} history_timestamp_format_string (@var{new_val})
Query or set the internal variable that specifies the format string
for the comment line that is written to the history file when Octave
exits.  The format string is passed to @code{strftime}.  The default
value is

@example
"# Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@@HOST>"
@end example
@seealso{strftime, history_file, history_size, saving_history}
@end deftypefn


@anchor{doc-EDITOR}
@deftypefn {Built-in Function} {@var{val} =} EDITOR ()
@deftypefnx {Built-in Function} {@var{old_val} =} EDITOR (@var{new_val})
Query or set the internal variable that specifies 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{"emacs"}.
@seealso{edit_history}
@end deftypefn


@node Customizing readline
@subsection Customizing @code{readline}

As mentioned earlier Octave uses the GNU readline library for
command-line editing and history features. It is possible to
customize how readline works through a configuration file.

@c FIXME -- need a brief description of the ~/.inputrc file here.

@anchor{doc-read_readline_init_file}
@deftypefn {Built-in Function} {} read_readline_init_file (@var{file})
Read the readline library initialization file @var{file}.  If
@var{file} is omitted, read the default initialization file (normally
@file{~/.inputrc}).

@xref{Readline Init File, , , readline, GNU Readline Library},
for details.
@end deftypefn


@node Customizing the Prompt
@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 @samp{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, up to the first `.'.

@item \H
The hostname.

@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 @samp{#}, otherwise a @samp{$}.

@item \nnn
The character whose character code in octal is @var{nnn}.

@item \\
A backslash.
@end table

@anchor{doc-PS1}
@deftypefn {Built-in Function} {@var{val} =} PS1 ()
@deftypefnx {Built-in Function} {@var{old_val} =} PS1 (@var{new_val})
Query or set the primary prompt string.  When executing interactively,
Octave displays the primary prompt when it is ready to read a command.

The default value of the primary prompt string 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 double-quoted
character string.
@xref{Strings}.
@seealso{PS2, PS4}
@end deftypefn


@anchor{doc-PS2}
@deftypefn {Built-in Function} {@var{val} =} PS2 ()
@deftypefnx {Built-in Function} {@var{old_val} =} PS2 (@var{new_val})
Query or set the secondary prompt string.  The secondary prompt is
printed when Octave is expecting additional input to complete a
command.  For example, if you are typing a for loop that spans several
lines, Octave will print the secondary prompt at the beginning of
each line after the first.  The default value of the secondary prompt
string is @code{"> "}.
@seealso{PS1, PS4}
@end deftypefn


@anchor{doc-PS4}
@deftypefn {Built-in Function} {@var{val} =} PS4 ()
@deftypefnx {Built-in Function} {@var{old_val} =} PS4 (@var{new_val})
Query or set the character string used to prefix output produced
when echoing commands when @code{echo_executing_commands} is enabled.
The default value is @code{"+ "}.
@xref{Invoking Octave from the Command Line}, for a description of
@code{--echo-commands}.
@seealso{echo_executing_commands, PS1, PS2}
@end deftypefn


@node Diary and Echo Commands
@subsection Diary and Echo Commands
@cindex diary of commands and output
@cindex command and output 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.

@anchor{doc-diary}
@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.

@anchor{doc-echo}
@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


@anchor{doc-echo_executing_commands}
@deftypefn {Built-in Function} {@var{val} =} echo_executing_commands ()
@deftypefnx {Built-in Function} {@var{old_val} =} echo_executing_commands (@var{new_val})
Query or set the internal variable that controls 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 deftypefn


@node Errors
@section How Octave Reports Errors
@cindex error messages
@cindex messages, error

Octave reports two kinds of errors for invalid programs.

A @dfn{parse error} occurs if Octave cannot understand something you
have typed.  For example, if you misspell a keyword,

@example
octave:13> functon y = f (x) y = x^2; endfunction
@end example

@noindent
Octave will respond immediately with a message like this:

@example
parse error:

  functon y = f (x) y = x^2; endfunction
          ^
@end example

@noindent
For most parse errors, Octave uses a caret (@samp{^}) to mark the point
on the line where it was unable to make sense of your input.  In this
case, Octave generated an error message because the keyword
@code{function} was misspelled.  Instead of seeing @samp{function f},
Octave saw two consecutive variable names, which is invalid in this
context.  It marked the error at @code{y} because the first name by
itself was accepted as valid input.

Another class of error message occurs at evaluation time.  These
errors are called @dfn{run-time errors}, or sometimes
@dfn{evaluation errors} because they occur when your program is being
@dfn{run}, or @dfn{evaluated}.  For example, if after correcting the
mistake in the previous function definition, you type

@example
octave:13> f ()
@end example

@noindent
Octave will respond with

@c Using 'smallexample' to make text fit on page when creating smallbook.
@smallexample
@group
error: `x' undefined near line 1 column 24
error: evaluating expression near line 1, column 24
error: evaluating assignment expression near line 1, column 22
error: called from `f'
@end group
@end smallexample

@noindent
This error message has several parts, and gives you quite a bit of
information to help you locate the source of the error.  The messages
are generated from the point of the innermost error, and provide a
traceback of enclosing expressions and function calls.

In the example above, the first line indicates that a variable named
@samp{x} was found to be undefined near line 1 and column 24 of some
function or expression.  For errors occurring within functions, lines
are counted from the beginning of the file containing the function
definition.  For errors occurring at the top level, the line number
indicates the input line number, which is usually displayed in the
prompt string.

The second and third lines in the example indicate that the error
occurred within an assignment expression, and the last line of the error
message indicates that the error occurred within the function @code{f}.
If the function @code{f} had been called from another function, for
example, @code{g}, the list of errors would have ended with one more
line:

@example
error: called from `g'
@end example

These lists of function calls usually make it fairly easy to trace the
path your program took before the error occurred, and to correct the
error before trying again.

@node Executable Octave Programs
@section Executable Octave Programs
@cindex executable scripts
@cindex scripts
@cindex self contained programs
@cindex program, self contained
@cindex @samp{#!}

Once you have learned Octave, you may want to write self-contained
Octave scripts, using the @samp{#!} script mechanism.  You can do this
on 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.}.

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.

For example, you could create a text file named @file{hello}, containing
the following lines:

@example
@group
#! @var{octave-interpreter-name} -qf
# a sample Octave program
printf ("Hello, world!\n");
@end group
@end example

@noindent
(where @var{octave-interpreter-name} should be replaced with the full
file name for your Octave binary).  Note that this will only work if
@samp{#!} appears at the very beginning of the file. 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 @samp{-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 from the Command Line}.

Note that some operating systems may place a limit on the number of
characters that are recognized after @samp{#!}.  Also, the various
shells/systems parse differently the arguments appearing in a @samp{#!} 
line.  The majority of them group together all the arguments in a string
and pass it to the interpreter as a single argument.  In this case, the
following script:

@example
@group
#! @var{octave-interpreter-name} -q -f # comment
@end group
@end example

@noindent
is equivalent to type at the command line:

@example
@group
octave "-q -f # comment"
@end group
@end example

@noindent
which would obviously produce an error message.  Unfortunately, it is
impossible for Octave to know whether it has been called from the command
line or from a @samp{#!} script, so some care is needed when using the
@samp{#!} mechanism.

Note that when Octave is started from an executable script, the built-in
function @code{argv} returns a cell array containing the command line
arguments passed to an executable Octave script, not the arguments
passed to the Octave interpreter on the @samp{#!} line of the script.
For example, the following program will reproduce the command line that
is used to execute script, not @samp{-qf}.

@example
@group
#! /bin/octave -qf
printf ("%s", program_name ());
arg_list = argv ();
for i = 1:nargin
  printf (" %s", arg_list@{i@});
endfor
printf ("\n");
@end group
@end example

@node Comments
@section Comments in Octave Programs
@cindex @samp{#}
@cindex @samp{%}
@cindex comments
@cindex use of comments
@cindex documenting Octave programs
@cindex programs

A @dfn{comment} is some text that is included in a program for the sake
of human readers, and that is not really part of the program.  Comments
can explain what the program does, and how it works.  Nearly all
programming languages have provisions for comments, because programs are
typically hard to understand without them.

In the Octave language, a comment starts with either the sharp sign
character, @samp{#}, or the percent symbol @samp{%} and continues to the
end of the line.  The Octave interpreter ignores the rest of a
line following a sharp sign or percent symbol.  For example, we could
have put the following into the function @code{f}:

@example
@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

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
@group
 usage: f (x, t)

 This function defines the right hand
 side functions for a set of nonlinear
 differential equations.
@end group
@end example

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.

