# HG changeset patch
# User Rik <rdrider0-list@yahoo.com>
# Date 1240005197 25200
# Node ID eb1747dbd360b0248bce426739e4b37a52b144c6
# Parent  6340043000c012cdc5528f8d80b0eecb1ff770c6
Update help strings for command line options

Add documentation for --no-init-path option
Add documentation for environment variables OCTAVE_SITE_INITFILE, OCTAVE_VERSION_INITFILE

diff --git a/doc/ChangeLog b/doc/ChangeLog
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2009-04-16  Rik  <rdrider0-list@yahoo.com>
+
+	* interpreter/basics.txi: Update help strings for command line options
+
 2009-04-11  David Bateman  <dbateman@free.fr>
 
 	* interpreter/contributors.in: Add Martin Helm.
diff --git a/doc/interpreter/basics.txi b/doc/interpreter/basics.txi
--- a/doc/interpreter/basics.txi
+++ b/doc/interpreter/basics.txi
@@ -63,12 +63,12 @@
 @cindex command options
 @cindex options, Octave command
 
-Here is a complete list of all the command line options that Octave
+Here is a complete list of the command line options that Octave
 accepts.
 
 
 @table @code
-@item --debug
+@item  --debug
 @itemx -d
 @cindex @code{--debug}
 @cindex @code{-d}
@@ -76,22 +76,22 @@
 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 --doc-cache-file
-@cindex @code{--doc-cache-file} @var{filename}
+@item --doc-cache-file @var{filename}
+@cindex @code{--doc-cache-file @var{filename}}
 Specify the name of the doc cache file to use.  The value of @var{filename}
 specified on the command line will override any value of
 @code{OCTAVE_DOC_CACHE_FILE} found in the environment, but not any commands
-in the system or user startup files that use the @code{doc_file_cache}
+in the system or user startup files that use the @code{doc_cache_file}
 function.
 
-@item --echo-commands
+@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
+Evaluate @var{code} and exit when finished unless @code{--persist} is also
 specified.
 
 @item --exec-path @var{path}
@@ -102,7 +102,7 @@
 in the system or user startup files that set the built-in variable
 @code{EXEC_PATH}.
 
-@item --help
+@item  --help
 @itemx -h
 @itemx -?
 @cindex @code{--help}
@@ -112,9 +112,11 @@
 
 @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.
+Add path to the head of the search path for images.  The value of 
+@var{path} specified on the command line will override any value of 
+@code{OCTAVE_IMAGE_PATH} found in the environment, but not any commands 
+in the system or user startup files that set the built-in variable 
+@code{IMAGE_PATH}.
 
 @item --info-file @var{filename}
 @cindex @code{--info-file @var{filename}}
@@ -132,7 +134,7 @@
 commands in the system or user startup files that use the
 @code{info_program} function.
 
-@item --interactive
+@item  --interactive
 @itemx -i
 @cindex @code{--interactive}
 @cindex @code{-i}
@@ -140,13 +142,24 @@
 remote shell command or inside an Emacs shell buffer.  For another way
 to run Octave within Emacs, see @ref{Emacs Octave Support}.
 
-@item --no-history
+@item --line-editing
+@cindex @code{--line-editing}
+Force readline use for command-line editing.
+
+@item  --no-history
 @itemx -H
-Disable command-line history.
+@cindex @code{--no-history}
+@cindex @code{-H}
+Disable recording of command-line history.
 
 @item --no-init-file
 @cindex @code{--no-init-file}
-Don't read the @file{~/.octaverc} or @file{.octaverc} files.
+Don't read the initialization files @file{~/.octaverc} and @file{.octaverc}.
+
+@item --no-init-path
+@cindex @code{--no-init-path}
+Don't initialize the search path for function files to include default 
+locations.
 
 @item --no-line-editing
 @cindex @code{--no-line-editing}
@@ -154,9 +167,9 @@
 
 @item --no-site-file
 @cindex @code{--no-site-file}
-Don't read the site-wide @file{octaverc} file.
+Don't read the site-wide @file{octaverc} initialization files.
 
-@item --norc
+@item  --norc
 @itemx -f
 @cindex @code{--norc}
 @cindex @code{-f}
@@ -164,21 +177,22 @@
 This is equivalent to using both of the options @code{--no-init-file}
 and @code{--no-site-file}.
 
-@item --path @var{path}
+@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
+Add path to the head of the search path 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
+@cindex @code{--persist}
 Go to interactive mode after @code{--eval} or reading from a file
 named on the command line.
 
-@item --silent
+@item  --silent
 @itemx --quiet
 @itemx -q
 @cindex @code{--silent}
@@ -186,7 +200,7 @@
 @cindex @code{-q}
 Don't print the usual greeting and version message at startup.
 
-@item --traditional
+@item  --traditional
 @itemx --braindead
 @cindex @code{--traditional}
 @cindex @code{--braindead}
@@ -198,6 +212,7 @@
 PS1                     = ">> "
 PS2                     = ""
 beep_on_error           = true
+confirm_recursive_rmdir = false
 crash_dumps_octave_core = false
 default_save_options    = "-mat-binary"
 fixed_point_format      = true
@@ -218,13 +233,13 @@
 @end group
 @end example
 
-@item --verbose
+@item  --verbose
 @itemx -V
 @cindex @code{--verbose}
 @cindex @code{-V}
 Turn on verbose output.
 
-@item --version
+@item  --version
 @itemx -v
 @cindex @code{--version}
 @cindex @code{-v}
@@ -235,7 +250,7 @@
 @code{--persist} is also specified.
 @end table
 
-Octave also includes several built-in variables that contain information
+Octave also includes several functions which return information 
 about the command line, including the number of arguments and all of the
 options.
 
@@ -245,22 +260,24 @@
 
 @DOCSTRING(program_invocation_name)
 
-Here is an example of using these functions to reproduce Octave's
-command line.
+Here is an example of using these functions to reproduce the command 
+line which invoked Octave.
 
 @example
+@group
 printf ("%s", program_name ());
 arg_list = argv ();
 for i = 1:nargin
   printf (" %s", arg_list@{i@});
 endfor
 printf ("\n");
+@end group
 @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}.
+@xref{Indexing Cell Arrays}, for an explanation of how to retrieve objects
+from cell arrays, and @ref{Defining Functions}, for information about the 
+variable @code{nargin}.
 
 @node Startup Files
 @subsection Startup Files
@@ -275,28 +292,34 @@
 
 @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.
+@cindex site startup file
+where @var{octave-home} is the directory in which 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.  Care should be taken when making changes to this file 
+since all users of Octave at your site will be affected.  The default file 
+may be overridden by the environment variable @w{@code{OCTAVE_SITE_INITFILE}}.
 
 @item @var{octave-home}/share/octave/@var{version}/m/startup/octaverc
-Where @var{octave-home} is the directory in which all of Octave is
+@cindex version startup file
+where @var{octave-home} is the directory in which 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.
+to the default Octave environment can be made globally for all users of
+a particular version of Octave.  Care should be taken when making
+changes to this file since all users of Octave at your site will be
+affected.  The default file may be overridden by the environment variable
+@w{@code{OCTAVE_VERSION_INITFILE}}.
 
 @item ~/.octaverc
+@cindex personal startup file
 @cindex @code{~/.octaverc}
 This file is used to make personal changes to the default 
 Octave environment.
 
 @item .octaverc
+@cindex project startup file
 @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
@@ -754,12 +777,14 @@
 Octave will respond immediately with a message like this:
 
 @example
+@group
 parse error:
 
   syntax error
 
 >>> functon y = f (x) y = x^2; endfunction
              ^
+@end group
 @end example
 
 @noindent
diff --git a/run-octave.in b/run-octave.in
--- a/run-octave.in
+++ b/run-octave.in
@@ -70,5 +70,5 @@
 OCTAVE_SITE_INITFILE="$top_srcdir/scripts/startup/main-rcfile" \
 LD_PRELOAD="$liboctinterp $liboctave $libcruft" \
 %library_path_var%="$builddir/src:$builddir/liboctave:$builddir/libcruft:$%library_path_var%" \
-  exec $driver "$builddir/src/octave" --no-initial-path --path="$LOADPATH" --image-path="$IMAGEPATH" --doc-cache-file="$DOCFILE" --info-file="$INFOFILE" "$@"
+  exec $driver "$builddir/src/octave" --no-init-path --path="$LOADPATH" --image-path="$IMAGEPATH" --doc-cache-file="$DOCFILE" --info-file="$INFOFILE" "$@"
 
diff --git a/src/defaults.cc b/src/defaults.cc
--- a/src/defaults.cc
+++ b/src/defaults.cc
@@ -322,7 +322,7 @@
 static void
 set_local_site_defaults_file (void)
 {
-  std::string lsf = octave_env::getenv ("OCTAVE_LOCAL_SITE_INITFILE");
+  std::string lsf = octave_env::getenv ("OCTAVE_SITE_INITFILE");
 
   if (lsf.empty ())
     {
@@ -336,7 +336,7 @@
 static void
 set_site_defaults_file (void)
 {
-  std::string sf = octave_env::getenv ("OCTAVE_SITE_INITFILE");
+  std::string sf = octave_env::getenv ("OCTAVE_VERSION_INITFILE");
 
   if (sf.empty ())
     {
diff --git a/src/octave.cc b/src/octave.cc
--- a/src/octave.cc
+++ b/src/octave.cc
@@ -107,7 +107,7 @@
 static bool read_site_files = true;
 
 // TRUE means we set the initial path to configured defaults.
-// (--no-initial-path)
+// (--no-init-path)
 static bool set_initial_path = true;
 
 // TRUE means we don't print the usual startup message.
@@ -152,7 +152,7 @@
 #define NO_INIT_FILE_OPTION 7
 #define NO_LINE_EDITING_OPTION 8
 #define NO_SITE_FILE_OPTION 9
-#define NO_INITIAL_PATH_OPTION 10
+#define NO_INIT_PATH_OPTION 10
 #define PERSIST_OPTION 11
 #define TRADITIONAL_OPTION 12
 #define LINE_EDITING_OPTION 13
@@ -174,7 +174,7 @@
     { "no-init-file",     prog_args::no_arg,       0, NO_INIT_FILE_OPTION },
     { "no-line-editing",  prog_args::no_arg,       0, NO_LINE_EDITING_OPTION },
     { "no-site-file",     prog_args::no_arg,       0, NO_SITE_FILE_OPTION },
-    { "no-initial-path",  prog_args::no_arg,       0, NO_INITIAL_PATH_OPTION },
+    { "no-init-path",     prog_args::no_arg,       0, NO_INIT_PATH_OPTION },
     { "norc",             prog_args::no_arg,       0, 'f' },
     { "path",             prog_args::required_arg, 0, 'p' },
     { "persist",          prog_args::no_arg,       0, PERSIST_OPTION },
@@ -509,20 +509,21 @@
   --eval CODE             Evaluate CODE.  Exit when done unless --persist.\n\
   --exec-path PATH        Set path for executing subprograms.\n\
   --help, -h, -?          Print short help message and exit.\n\
-  --image-path PATH       Set initial IMAGE_PATH to PATH.\n\
+  --image-path PATH       Add PATH to head of image search path.\n\
   --info-file FILE        Use top-level info file FILE.\n\
   --info-program PROGRAM  Use PROGRAM for reading info files.\n\
   --interactive, -i       Force interactive behavior.\n\
   --line-editing          Force readline use for command-line editing.\n\
   --no-history, -H        Don't save commands to the history list\n\
   --no-init-file          Don't read the ~/.octaverc or .octaverc files.\n\
+  --no-init-path          Don't initialize function search path.\n\
   --no-line-editing       Don't use readline for command-line editing.\n\
   --no-site-file          Don't read the site-wide octaverc file.\n\
   --norc, -f              Don't read any initialization files.\n\
-  --path PATH, -p PATH    Set initial function search path to PATH.\n\
+  --path PATH, -p PATH    Add PATH to head of function search path.\n\
   --persist               Go interactive after --eval or reading from FILE.\n\
   --silent, -q            Don't print message at startup.\n\
-  --traditional           Set compatibility variables.\n\
+  --traditional           Set variables for closer MATLAB compatibility.\n\
   --verbose, -V           Enable verbose output in some cases.\n\
   --version, -v           Print version number and exit.\n\
 \n\
@@ -739,9 +740,9 @@
 	    bind_internal_variable ("info_program", args.optarg ());
 	  break;
 
-        case LINE_EDITING_OPTION:
-          forced_line_editing = true;
-          break;
+	case LINE_EDITING_OPTION:
+	  forced_line_editing = true;
+	  break;
 
 	case NO_INIT_FILE_OPTION:
 	  read_init_files = false;
@@ -755,7 +756,7 @@
 	  read_site_files = 0;
 	  break;
 
-	case NO_INITIAL_PATH_OPTION:
+	case NO_INIT_PATH_OPTION:
 	  set_initial_path = false;
 	  break;