--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/basics.txi	Tue Oct 19 10:08:42 1999 +0000
@@ -0,0 +1,1130 @@
+@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 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
+* Invoking Octave::             
+* Quitting Octave::             
+* Getting Help::                
+* Command Line Editing::        
+* Errors::                      
+* 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 @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, 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.
+
+@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 --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 set the built-in variable
+@code{INFO_FILE}.
+
+@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 set the built-in
+variable @code{INFO_PROGRAM}.
+
+@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-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 built-in variable @code{LOADPATH}.
+
+@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}
+Set initial values for user-preference variables to the following
+values for compatibility with @sc{Matlab}.
+
+@example
+PS1                           = ">> "
+PS2                           = ""
+beep_on_error                 = 1
+default_save_format           = "mat-binary"
+define_all_return_values      = 1
+do_fortran_indexing           = 1
+crash_dumps_octave_core       = 0
+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
+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
+@code{argv} would be a list of strings with the elements
+@code{--no-line-editing} and @code{--silent}.
+
+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
+
+@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
+@samp{@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"}.
+
+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
+
+Here is an example of using these variables to reproduce Octave's
+command line.
+
+@example
+printf ("%s", program_name);
+for i = 1:nargin
+  printf (" %s", argv(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,  , 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 @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.
+
+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.  For example,
+
+@example
+@group
+function print_flops_at_exit ()
+  printf ("\n%s\n", system ("fortune"));
+  fflush (stdout);
+endfunction
+atexit ("print_flops_at_exit");
+@end group
+@end example
+
+@noindent
+will print a message 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 running, 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{"@var{octave-home}/info/octave.info"}, where
+@var{octave-home} is the directory where all of Octave is installed.
+@end defvr
+
+@defvr {Built-in Variable} INFO_PROGRAM
+The variable @code{INFO_PROGRAM} names the info program to run.  Its
+initial value is
+@code{"@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}/info"},
+where @var{octave-home} is the directory where all of Octave is
+installed, @var{version} is the Octave version number, and @var{arch} is
+the machine type.  The value of @code{INFO_PROGRAM} 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 the
+built-in variable @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 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 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 @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.
+
+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-@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, 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-@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
+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 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
+
+@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 @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.
+
+@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
+
+@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{"emacs"}.
+@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 nonzero, 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 @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
+
+@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 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
+
+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
+
+@example
+@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 example
+
+This error message has several parts, and gives you quite a bit of
+information to help you locate the source of the error.  The messages
+are generated from the point of the innermost error, and provide a
+traceback of enclosing 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, Comments, Errors, Getting Started
+@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.}
+
+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).  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}.  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
+@group
+#! /bin/octave -qf
+printf ("%s", program_name);
+for i = 1:nargin
+  printf (" %s", argv(i,:));
+endfor
+printf ("\n");
+@end group
+@end example
+
+@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
+
+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.
+