changeset 9035:57649dcecb55

Documentation cleanup of basics.texi Added documentation for new block comments feature Spellcheck Miscellaneous language cleanup for clarity
author Rik <rdrider0-list@yahoo.com>
date Sat, 21 Mar 2009 08:29:37 -0700
parents 52515efc50c0
children 58604c45ca74
files doc/interpreter/basics.txi doc/interpreter/octave.texi scripts/help/lookfor.m src/input.cc src/oct-hist.cc src/toplev.cc
diffstat 6 files changed, 110 insertions(+), 46 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/basics.txi
+++ b/doc/interpreter/basics.txi
@@ -191,7 +191,7 @@
 @cindex @code{--traditional}
 @cindex @code{--braindead}
 For compatibility with @sc{Matlab}, set initial values for
-user-preferences to the following values
+user preferences to the following values
 
 @example
 @group
@@ -268,7 +268,7 @@
 @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,
+the following list.  These files may contain any valid Octave commands,
 including function definitions.
 
 @cindex startup files
@@ -293,7 +293,7 @@
 
 @item ~/.octaverc
 @cindex @code{~/.octaverc}
-This file is normally used to make personal changes to the default
+This file is used to make personal changes to the default 
 Octave environment.
 
 @item .octaverc
@@ -301,8 +301,8 @@
 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}.
+command in the @file{~/.octaverc} file will affect the directory where
+Octave searches for @file{.octaverc}.
 
 If you start Octave in your home directory, commands from the file
 @file{~/.octaverc} will only be executed once.
@@ -386,7 +386,7 @@
 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
+@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}.
 
@@ -514,7 +514,7 @@
 @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
+otherwise have a special meaning (e.g., @key{TAB}, @kbd{C-q}, etc.), or
 for quickly correcting typing mistakes.
 
 @table @kbd
@@ -588,8 +588,8 @@
 @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
+Accept the current line regardless of where the cursor is.  If the line is
+non-empty, add it to the history list.  If the line was a history
 line, then restore the history line to its original state.
 
 @item C-p
@@ -643,7 +643,7 @@
 @subsection Customizing @code{readline}
 
 As mentioned earlier Octave uses the GNU readline library for
-command-line editing and history features. It is possible to
+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.
@@ -773,7 +773,7 @@
 
 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{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
 
@@ -808,7 +808,7 @@
 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
+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:
 
@@ -816,7 +816,7 @@
 error:   g at line 1, column 17
 @end example
 
-These lists of function calls usually make it fairly easy to trace the
+These lists of function calls make it fairly easy to trace the
 path your program took before the error occurred, and to correct the
 error before trying again.
 
@@ -852,7 +852,7 @@
 @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
+@samp{#!} appears at the very beginning of the file.  After making this
 file executable
 (with the @code{chmod} command), you can simply type:
 
@@ -873,7 +873,7 @@
 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
+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
@@ -929,32 +929,90 @@
 
 @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
+of human readers, and that 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.
 
+@menu
+* Single Line Comments::
+* Block Comments::
+* Comments and the Help System::                    
+@end menu
+
+@node Single Line Comments
+@subsection Single Line Comments
+@cindex @samp{#}
+@cindex @samp{%}
+
 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}:
+end of the line.  Any text following the sharp sign or percent symbol is
+ignored by the Octave interpreter and not executed.  The following example
+shows whole line and partial line comments.
+@example
+@group
+function countdown
+  # Count down for main rocket engines 
+  disp(3);
+  disp(2);
+  disp(1);
+  disp("Blast Off!");  # Rocket leaves pad
+endfunction
+@end group
+@end example
+
+@node Block Comments
+@subsection Block Comments
+@cindex multi-line comments
+@cindex @samp{#@{}
+@cindex @samp{%@{}
 
+Entire blocks of code can be commented by enclosing the code between 
+matching @samp{#@{} and @samp{#@}} or @samp{%@{} and @samp{%@}} markers.  
+For example,
+@example
+@group
+function quick_countdown
+  # Count down for main rocket engines 
+  disp(3);
+ #@{
+  disp(2);
+  disp(1);
+ #@}
+  disp("Blast Off!");  # Rocket leaves pad
+endfunction
+@end group
+@end example
+
+@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.
+
+@node Comments and the Help System
+@subsection Comments and the Help System
+@cindex documenting functions
+@cindex documenting user scripts
+@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,
 @example
 @group
 function xdot = f (x, t)
 
 # usage: f (x, t)
 #
-# This function defines the right hand
+# This function defines the right-hand
 # side functions for a set of nonlinear
 # differential equations.
 
@@ -964,18 +1022,13 @@
 @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
+ This function defines the right-hand
  side functions for a set of nonlinear
  differential equations.
 @end group
@@ -986,3 +1039,6 @@
 purpose of a comment is to help you or another person understand the
 program at a later time.
 
+The @code{help} parser currently only recognizes single line comments
+(@pxref{Single Line Comments}) and not block comments for the initial 
+help text. 
--- a/doc/interpreter/octave.texi
+++ b/doc/interpreter/octave.texi
@@ -252,6 +252,12 @@
 * Customizing the Prompt::      
 * Diary and Echo Commands::     
 
+Comments
+
+* Single Line Comments::
+* Block Comments::
+* Comments and the Help System::                    
+
 Data Types
 
 * Built-in Data Types::         
--- a/scripts/help/lookfor.m
+++ b/scripts/help/lookfor.m
@@ -17,24 +17,24 @@
 ## -*- texinfo -*-
 ## @deftypefn {Command} lookfor @var{str}
 ## @deftypefnx {Command} lookfor -all @var{str}
-## @deftypefnx {Function} {[@var{fun}, @var{helpstring}] = } lookfor (@var{str})
-## @deftypefnx {Function} {[@var{fun}, @var{helpstring}] = } lookfor ('-all', @var{str})
+## @deftypefnx {Function} {[@var{fun}, @var{helpstring}] =} lookfor (@var{str})
+## @deftypefnx {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
+## 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.
+## 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
+## 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
+## 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
+## 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 deftypefn
--- a/src/input.cc
+++ b/src/input.cc
@@ -1280,7 +1280,7 @@
 @deftypefnx {Built-in Function} {@var{old_val} =} PS2 (@var{new_val})\n\
 Query or set the secondary prompt string.  The secondary prompt is\n\
 printed when Octave is expecting additional input to complete a\n\
-command.  For example, if you are typing a for loop that spans several\n\
+command.  For example, if you are typing a @code{for} loop that spans several\n\
 lines, Octave will print the secondary prompt at the beginning of\n\
 each line after the first.  The default value of the secondary prompt\n\
 string is @code{\"> \"}.\n\
--- a/src/oct-hist.cc
+++ b/src/oct-hist.cc
@@ -551,7 +551,7 @@
 
 DEFUN (edit_history, args, ,
   "-*- texinfo -*-\n\
-@deffn {Command} edit_history options\n\
+@deffn {Command} edit_history [@var{first}] [@var{last}]\n\
 If invoked with no arguments, @code{edit_history} allows you to edit the\n\
 history list using the editor named by the variable @code{EDITOR}.  The\n\
 commands to be edited are first copied to a temporary file.  When you\n\
@@ -583,6 +583,7 @@
 the first command than the last command reverses the list of commands\n\
 before placing them in the buffer to be edited.  If both arguments are\n\
 omitted, the previous command in the history list is used.\n\
+@seealso{run_history}\n\
 @end deffn")
 {
   octave_value_list retval;
@@ -616,11 +617,11 @@
 (normally @file{~/.octave_hist}).\n\
 \n\
 @item @var{n}\n\
-Only display the most recent @var{n} lines of history.\n\
+Display only the most recent @var{n} lines of history.\n\
 \n\
 @item -q\n\
 Don't number the displayed lines of history.  This is useful for cutting\n\
-and pasting commands if you are using the X Window System.\n\
+and pasting commands using the X Window System.\n\
 @end table\n\
 \n\
 For example, to display the five most recent commands that you have\n\
@@ -644,9 +645,10 @@
 
 DEFUN (run_history, args, ,
   "-*- texinfo -*-\n\
-@deffn {Command} run_history [first] [last]\n\
+@deffn {Command} run_history [@var{first}] [@var{last}]\n\
 Similar to @code{edit_history}, except that the editor is not invoked,\n\
 and the commands are simply executed as they appear in the history list.\n\
+@seealso{edit_history}\n\
 @end deffn")
 {
   octave_value_list retval;
--- a/src/toplev.cc
+++ b/src/toplev.cc
@@ -1038,10 +1038,10 @@
 \n\
 @example\n\
 @group\n\
-function bye_bye ()\n\
+function last_words ()\n\
   disp (\"Bye bye\");\n\
 endfunction\n\
-atexit (\"bye_bye\");\n\
+atexit (\"last_words\");\n\
 @end group\n\
 @end example\n\
 \n\
@@ -1052,15 +1052,15 @@
 Register or unregister a function to be called when Octave exits,\n\
 depending on @var{flag}.  If @var{flag} is true, the function is\n\
 registered, if @var{flag} is false, it is unregistered.  For example,\n\
-after registering the function @code{bye_bye} as above,\n\
+after registering the function @code{last_words} as above,\n\
 \n\
 @example\n\
-atexit (\"bye_bye\", false);\n\
+atexit (\"last_words\", false);\n\
 @end example\n\
 \n\
 @noindent\n\
 will remove the function from the list and Octave will not call\n\
-the function @code{bye_by} when it exits.\n\
+the function @code{last_words} when it exits.\n\
 \n\
 Note that @code{atexit} only removes the first occurrence of a function\n\
 from the list, so if a function was placed in the list multiple\n\