octave-lyh: doc/interpreter/intro.texi comparison

comparison doc/interpreter/intro.texi @ 2653:e7908588548a

[project @ 1997-02-01 16:53:52 by jwe]

author	jwe
date	Sat, 01 Feb 1997 16:57:10 +0000
parents	31d5588dbb61
children	18192eea4973

comparison

equal deleted inserted replaced

-:69613a17f51a
+:e7908588548a
 @node Introduction, Invoking Octave, Preface, Top
 @chapter A Brief Introduction to Octave
 @cindex introduction
-This manual documents how to run, install and port Octave, and how
+This manual documents how to run, install and port Octave, and how to
-to report bugs.
+report bugs.
 Octave is a high-level language, primarily intended for numerical
 computations.  It provides a convenient command line interface for
 solving linear and nonlinear problems numerically, and for performing
 other numerical experiments.  It may also be used as a batch-oriented
 @c                  always use more funding.
 @menu
 * Running Octave::
 * Simple Examples::
-* Comments::
+* Conventions::
-* Executable Octave Programs::
-* Errors::
 @end menu
 @node Running Octave, Simple Examples, Introduction, Introduction
 @section Running Octave
 @cindex exiting octave
 @cindex quitting octave
 To exit Octave, type @samp{quit}, or @samp{exit} at the Octave prompt.
-@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
 On systems that support job control, you can suspend Octave by sending
 it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}.
-@node Simple Examples, Comments, Running Octave, Introduction
+@node Simple Examples, Conventions, Running Octave, Introduction
 @section Simple Examples
 The following chapters describe all of Octave's features in detail, but
 before doing that, it might be helpful to give a sampling of some of its
 capabilities.
 Octave sends output that is too long to fit on one screen through a
 pager like @code{less} or @code{more}.  Type a carriage return to
 advance one line, a space character to advance one page, and @samp{q} to
 exit the pager.
-@unnumberedsubsubsec Help via Info
 The part of Octave's help facility that allows you to read the complete
-text of the printed manual from within Octave uses a program called
+text of the printed manual from within Octave normally uses a separate
-Info.  When you invoke Info you will be put into a menu driven program
+program called Info.  When you invoke Info you will be put into a menu
-that contains the entire Octave manual.  Help for using Info is provided
+driven program that contains the entire Octave manual.  Help for using
-in this manual in @ref{Using Info}.
+Info is provided in this manual in @ref{Help}.
-@node Comments, Executable Octave Programs, Simple Examples, Introduction
+@node Conventions,  , Simple Examples, Introduction
-@section Comments in Octave Programs
+@section Conventions
-@cindex @samp{#}
-@cindex @samp{%}
+This section explains the notational conventions that are used in this
-@cindex comments
+manual.  You may want to skip this section and refer back to it later.
-@cindex use of comments
-@cindex documenting Octave programs
+@menu
-@cindex programs, documenting
+* Fonts::
+* Evaluation Notation::
-A @dfn{comment} is some text that is included in a program for the sake
+* Printing Notation::
-of human readers, and that is not really part of the program.  Comments
+* Error Messages::
-can explain what the program does, and how it works.  Nearly all
+* Format of Descriptions::
-programming languages have provisions for comments, because programs are
+@end menu
-typically hard to understand without them.
+@node Fonts, Evaluation Notation, Conventions, Conventions
-In the Octave language, a comment starts with either the sharp sign
+@subsection Fonts
-character, @samp{#}, or the percent symbol @samp{%} and continues to the
+@cindex fonts
-end of the line.  The Octave interpreter ignores the rest of a
-line following a sharp sign or percent symbol.  For example, we could
+Examples of Octave code appear in this font or form: @code{svd (a)}.
-have put the following into the function @code{f}:
+Names that represent arguments or metasyntactic variables appear
+in this font or form: @var{first-number}.
-@smallexample
-function xdot = f (x, t)
+@node Evaluation Notation, Printing Notation, Fonts, Conventions
+@subsection Evaluation Notation
-# usage: f (x, t)
+@cindex evaluation notation
-#
+@cindex documentation notation
-# This function defines the right-hand-side functions for a set of
-# nonlinear differential equations.
+In the examples in this manual, results from expressions that you
+evaluate are indicated with @samp{@result{}}.  For example,
-r = 0.25
+@example
-and so on...
+@group
+sqrt (2)
-endfunction
-@end smallexample
+@result{} 1.4142
+@end group
-The @code{help} command (@pxref{Help}) is able to find the first block
+@end example
-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
+@noindent
-commands to get help for built-in functions, and for functions that you
+You can read this as ``@code{sqrt (2)} evaluates to 1.4142''.
-have defined.  For example, after defining the function @code{f} above,
-the command
+In some cases, matrix values that are returned by expressions are
+displayed like this
-@example
-help f
+@example
-@end example
+@group
+[1, 2; 3, 4] == [1, 3; 2, 4]
-@noindent
-produces the output
+@result{} [ 1, 0; 0, 1 ]
+@end group
-@smallexample
+@end example
-usage: f (x, t)
+@noindent
-This function defines the right-hand-side functions for a set of
+and in other cases, they are displayed like this
-nonlinear differential equations.
-@end smallexample
+@example
+@group
-Although it is possible to put comment lines into keyboard-composed
+eye (3)
-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
+@result{}  1  0  0
-program at a later time.
+0  1  0
+0  0  1
-@node Executable Octave Programs, Errors, Comments, Introduction
+@end group
-@section Executable Octave Programs
+@end example
-@cindex executable scripts
-@cindex scripts, executable
+@noindent
-@cindex self contained programs
+in order to clearly show the structure of the result.
-@cindex program, self contained
-@cindex @samp{#!}
+Sometimes to help describe one expression, another expression is
+shown that produces identical results.  The exact equivalence of
-Once you have learned Octave, you may want to write self-contained
+expressions is indicated with @samp{@equiv{}}.  For example,
-Octave scripts, using the @samp{#!} script mechanism.  You can do this
-on GNU systems and on many Unix systems @footnote{The @samp{#!}
+@example
-mechanism works on Unix systems derived from Berkeley Unix, System V
+@group
-Release 4, and some System V Release 3 systems.}
+rot90 ([1, 2; 3, 4], -1)
+@equiv{}
-For example, you could create a text file named @file{hello}, containing
+rot90 ([1, 2; 3, 4], 3)
-the following lines:
+@equiv{}
+rot90 ([1, 2; 3, 4], 7)
-@example
+@end group
-@group
+@end example
-#! @value{OCTAVEHOME}/bin/octave -qf
+@node Printing Notation, Error Messages, Evaluation Notation, Conventions
-# a sample Octave program
+@subsection Printing Notation
-printf ("Hello, world!\n");
+@cindex printing notation
-@end group
-@end example
+Many of the examples in this manual print text when they are
+evaluated.  Examples in this manual indicate printed text with
-@noindent
+@samp{@print{}}.  The value that is returned by evaluating the
-After making this file executable (with the @code{chmod} command), you
+expression (here @code{1}) is displayed with @samp{@result{}} and
-can simply type:
+follows on a separate line.
 @example
-hello
+@group
-@end example
+printf ("foo %s\n", "bar")
-@noindent
+@print{} foo bar
-at the shell, and the system will arrange to run Octave @footnote{The
-line beginning with @samp{#!} lists the full file name of an interpreter
+@result{} 1
-to be run, and an optional initial command line argument to pass to that
+@end group
-interpreter.  The operating system then runs the interpreter with the
+@end example
-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.
+@node Error Messages, Format of Descriptions, Printing Notation, Conventions
-The rest of the argument list will either be options to Octave, or data
+@subsection Error Messages
-files, or both.  The @code{-qf} option is usually specified in
+@cindex error message notation
-stand-alone Octave programs to prevent them from printing the normal
-startup message, and to keep them from behaving differently depending on
+Some examples signal errors.  This normally displays an error message
-the contents of a particular user's @file{~/.octaverc} file.
+on your terminal.  Error messages are shown on a line starting with
-@xref{Invoking Octave}.} as if you had typed:
+@samp{@error{}}.  Note that @samp{@error{}} itself does not appear on
+your terminal.
-@example
-octave hello
+@example
-@end example
+struct_elements ([1, 2; 3, 4])
+@error{} struct_elements: wrong type argument `matrix'
-@noindent
+@end example
-Self-contained Octave scripts are useful when you want to write a
-program which users can invoke without knowing that the program is
+@node Format of Descriptions,  , Error Messages, Conventions
-written in the Octave language.
+@subsection Format of Descriptions
+@cindex description format
-@node Errors,  , Executable Octave Programs, Introduction
-@section Errors
+Functions, commands, and variables are described in this manual in a
+uniform format.  The first line of a description contains the name of
-There are two classes of errors that Octave produces when it encounters
+the item followed by its arguments, if any.
-input that it is unable to understand, or when it is unable to perform
+@ifinfo
-an action.
+The category---function, variable, or whatever---appears at the
+beginning of the line.
-A @dfn{parse error} occurs if Octave cannot understand something you
+@end ifinfo
-have typed.  For example, if you misspell a keyword,
+@iftex
+The category---function, variable, or whatever---is printed next to the
-@example
+right margin.
-octave:13> functon y = f (x) y = x^2; endfunction
+@end iftex
-@end example
+The description follows on succeeding lines, sometimes with examples.
-@noindent
+@menu
-Octave will respond immediately with a message like this:
+* A Sample Function Description::
+* A Sample Command Description::
-@example
+* A Sample Variable Description::
-parse error:
+@end menu
-functon y = f (x) y = x^2; endfunction
+@node A Sample Function Description, A Sample Command Description, Format of Descriptions, Format of Descriptions
-^
+@subsubsection A Sample Function Description
-@end example
+@cindex function descriptions
-@noindent
+In a function description, the name of the function being described
-For most parse errors, Octave uses a caret (@samp{^}) to mark the point
+appears first.  It is followed on the same line by a list of parameters.
-on the line where it was unable to make sense of your input.  In this
+The names used for the parameters are also used in the body of the
-case, Octave generated an error message because the keyword
+description.
-@code{function} was misspelled.  Instead of seeing @samp{function f},
-Octave saw two consecutive variable names, which is invalid in this
+Here is a description of an imaginary function @code{foo}:
-context.  It marked the error at the @code{y} because the first name by
-itself was accepted as valid input.
+@deftypefn {Function} {} foo (@var{x}, @var{y}, @dots{})
+The function @code{foo} subtracts @var{x} from @var{y}, then adds the
-Another class of error message occurs occurs at evaluation time.  These
+remaining arguments to the result.  If @var{y} is not supplied, then the
-errors are called @dfn{run-time errors}, or sometimes
+number 19 is used by default.
-@dfn{evaluation errors} because they occur when your program is being
-@dfn{run}, or @dfn{evaluated}.  For example, if after correcting the
+@example
-mistake in the previous function definition, you type
+@group
+foo (1, [3, 5], 3, 9)
-@example
-octave:13> f ()
+@result{} [ 14, 16 ]
-@end example
+foo (5)
-@noindent
-Octave will respond with
+@result{} 14
+@end group
-@example
+@end example
-@group
-error: `x' undefined near line 1 column 24
+More generally,
-error: evaluating expression near line 1, column 24
-error: evaluating assignment expression near line 1, column 22
+@example
-error: called from `f'
+@group
-@end group
+foo (@var{w}, @var{x}, @var{y}, @dots{})
-@end example
+@equiv{}
+@var{x} - @var{w} + @var{y} + @dots{}
-This error message has several parts, and gives you quite a bit of
+@end group
-information to help you locate the source of the error.  The messages
+@end example
-are generated from the point of the innermost error, and provide a
+@end deftypefn
-traceback of enclosing expressions and function calls.
+Any parameter whose name contains the name of a type (e.g.,
-In the example above, the first line indicates that a variable named
+@var{integer}, @var{integer1} or @var{matrix}) is expected to be of that
-@samp{x} was found to be undefined near line 1 and column 24 of some
+type.  Parameters named @var{object} may be of any type.  Parameters
-function or expression.  For errors occurring within functions, lines
+with other sorts of names (e.g., @var{new_file}) are discussed
-from the beginning of the file containing the function definition.  For
+specifically in the description of the function.  In some sections,
-errors occurring at the top level, the line number indicates the input
+features common to parameters of several functions are described at the
-line number, which is usually displayed in the prompt string.
+beginning.
-The second and third lines in the example indicate that the error
+Functions in Octave may be defined in several different ways.  The
-occurred within an assignment expression, and the last line of the error
+catagory name for functions may include another name that indicates the
-message indicates that the error occurred within the function @samp{f}.
+way that the function is defined.  These additional tags include
-If the function @samp{f} had been called from another function, for
-example, @samp{g}, the list of errors would have ended with one more
+@table @asis
-line:
+@item Built-in Function
+The function described is written in a language like C++, C, or Fortran,
-@example
+and is part of the compiled Octave binary.
-error: called from `g'
-@end example
+@item Loadable Function
+The function described is written in a language like C++, C, or Fortran.
-These lists of function calls usually make it fairly easy to trace the
+On systems that support dynamic linking of user-supplied functions, it
-path your program took before the error occurred, and to correct the
+may be automatically linked while Octave is running, but only if it is
-error before trying again.
+needed.  @xref{Dynamically Linked Functions}.
+@item 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
+@cindex command descriptions
+Command descriptions have a format similar to function descriptions,
+except that the word `Function' is replaced by `Command.  Commands are
+functions that are called without surrounding their arguments in
+parentheses.  For example, here is the description for Octave's
+@code{cd} command:
+@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.
+@end deffn
+@node A Sample Variable Description,  , A Sample Command Description, Format of Descriptions
+@subsubsection A Sample Variable Description
+@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.
+Here is a description of the imaginary user option
+@code{do_what_i_mean_not_what_i_say}.
+@defvr {User Option} 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.

Mercurial > hg > octave-lyh

comparison doc/interpreter/intro.texi @ 2653:e7908588548a