# HG changeset patch # User Rik # Date 1240066484 25200 # Node ID b04f95fabbf93ad1173d9334144fc31b38806b42 # Parent a3739e27b017ee79851e1db649a0985bb485eadd Update sections 2.5, 2.6, 2.7 of basics.txi Sample parse error changed to a simpler example diff -r a3739e27b017 -r b04f95fabbf9 doc/ChangeLog --- a/doc/ChangeLog Fri Apr 17 16:38:34 2009 -0700 +++ b/doc/ChangeLog Sat Apr 18 07:54:44 2009 -0700 @@ -1,3 +1,8 @@ +2009-04-17 Rik + + * interpreter/basics.txi: Update help text for sections 2.5, 2.6, 2.7 + of basics.txi + 2009-04-17 Rik * interpreter/basics.txi: Update help text for sections 2.4 of basics.txi diff -r a3739e27b017 -r b04f95fabbf9 doc/interpreter/basics.txi --- a/doc/interpreter/basics.txi Fri Apr 17 16:38:34 2009 -0700 +++ b/doc/interpreter/basics.txi Sat Apr 18 07:54:44 2009 -0700 @@ -780,7 +780,7 @@ have typed. For example, if you misspell a keyword, @example -octave:13> functon y = f (x) y = x^2; endfunction +octave:13> function y = f (x) y = x***2; endfunction @end example @noindent @@ -792,19 +792,18 @@ syntax error ->>> functon y = f (x) y = x^2; endfunction - ^ +>>> function y = f (x) y = x***2; endfunction + ^ @end group @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. +case, Octave generated an error message because the keyword for +exponentiation (@code{**}) was misspelled. It marked the error at the +third @samp{*} because the code leading up to this was correct but the final +@samp{*} was not understood. Another class of error message occurs at evaluation time. These errors are called @dfn{run-time errors}, or sometimes @@ -829,7 +828,7 @@ @end smallexample @noindent -This error message has several parts, and gives you quite a bit of +This error message has several parts, and gives 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. @@ -838,14 +837,14 @@ @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. +definition. For errors occurring outside of an enclosing function, +the line number indicates the input line number, which is usually displayed +in the primary prompt string. -The second and third lines in 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: +The second and third lines of the error message indicate that the error +occurred within the function @code{f}. If the function @code{f} had been +called from within another function, for example, @code{g}, the list of +errors would have ended with one more line: @example error: g at line 1, column 17 @@ -859,6 +858,7 @@ @section Executable Octave Programs @cindex executable scripts @cindex scripts +@cindex batch processing @cindex self contained programs @cindex program, self contained @cindex @samp{#!} @@ -871,10 +871,13 @@ 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. +written in the Octave language. Octave scripts are also used for batch +processing of data files. Once an algorithm has been developed and tested +in the interactive portion of Octave, it can be committed to an executable +script and used again and again on new data files. -For example, you could create a text file named @file{hello}, containing -the following lines: +As a trivial example of an executable Octave script, you might create a +text file named @file{hello}, containing the following lines: @example @group @@ -886,10 +889,10 @@ @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: +path and name of your Octave binary). Note that this will only work if +@samp{#!} appears at the very beginning of the file. After making the +file executable (with the @code{chmod} command on Unix systems), you can +simply type: @example hello @@ -903,23 +906,23 @@ octave hello @end example -The line beginning with @samp{#!} lists the full file name of an +The line beginning with @samp{#!} lists the full path and filename 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 +of the Octave executable. The rest of the argument list will either be +options to Octave, or data files, or both. The @samp{-qf} options are 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 +characters that are recognized after @samp{#!}. Also, the arguments +appearing in a @samp{#!} line are parsed differently by various +shells/systems. The majority of them group all the arguments together in one +string and pass it to the interpreter as a single argument. In this case, the following script: @example @@ -929,7 +932,7 @@ @end example @noindent -is equivalent to type at the command line: +is equivalent to typing at the command line: @example @group @@ -938,17 +941,17 @@ @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 +which will produce an error message. Unfortunately, it is +not possible for Octave to determine 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 +arguments passed to the 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}. +was used to execute the script, not @samp{-qf}. @example @group @@ -967,10 +970,9 @@ @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 an executable part of the program. +of human readers, and which is NOT an executable 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. @@ -1005,6 +1007,7 @@ @node Block Comments @subsection Block Comments +@cindex block comments @cindex multi-line comments @cindex @samp{#@{} @cindex @samp{%@{} @@ -1028,7 +1031,7 @@ @noindent will produce a very quick countdown from '3' to 'Blast Off' as the -lines "@code{disp(2);}" and "@code{disp(3);}" won't be executed. +lines "@code{disp(2);}" and "@code{disp(1);}" won't be executed. @node Comments and the Help System @subsection Comments and the Help System @@ -1037,10 +1040,10 @@ @cindex help, user-defined functions 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 the same commands used to get help -on built-in functions are available for user-defined functions. For -example, after defining the function @code{f} below, +block of comments in a function and return those as a documentation +string. This means that the same commands used to get help +on built-in functions are available for properly formatted user-defined +functions. For example, after defining the function @code{f} below, @example @group function xdot = f (x, t) @@ -1069,8 +1072,8 @@ @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 +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. diff -r a3739e27b017 -r b04f95fabbf9 src/defaults.cc --- a/src/defaults.cc Fri Apr 17 16:38:34 2009 -0700 +++ b/src/defaults.cc Sat Apr 18 07:54:44 2009 -0700 @@ -405,7 +405,7 @@ Query or set the internal variable that specifies the editor to\n\ use with the @code{edit_history} command. The default value is taken from\n\ the environment variable @w{@code{EDITOR}} when Octave starts. If the\n\ -enironment variable is not initialized, @w{@code{EDITOR}} will be set to\n\ +environment variable is not initialized, @w{@code{EDITOR}} will be set to\n\ @code{\"emacs\"}.\n\ @seealso{edit_history}\n\ @end deftypefn")