# HG changeset patch
# User John W. Eaton <jwe@octave.org>
# Date 1295431507 18000
# Node ID 21c3e1370b82fa0d67b59c1eddf1b443bb8d0d67
# Parent  90f8d12f196497d941403a69e99463fd049d2d9a
implement --list option for help function

diff -r 90f8d12f1964 -r 21c3e1370b82 doc/interpreter/intro.txi
--- a/doc/interpreter/intro.txi	Wed Jan 19 04:10:26 2011 -0500
+++ b/doc/interpreter/intro.txi	Wed Jan 19 05:05:07 2011 -0500
@@ -385,11 +385,11 @@
 
 In order to get good help you first need to know the name of the command
 that you want to use.  This name of the function may not always be
-obvious, but a good place to start is to just type @code{help}.
-This will show you all the operators, reserved words, functions,
-built-in variables, and function files.  An alternative is to search the
-documentation using the @code{lookfor} function.  This function is
-described in @ref{Getting Help}.
+obvious, but a good place to start is to just type @code{help --list}.
+This will show you all the operators, keywords, built-in functions,
+and loadable functions available in the current session of Octave.  An
+alternative is to search the documentation using the @code{lookfor}
+function.  This function is described in @ref{Getting Help}.
 
 Once you know the name of the function you wish to use, you can get more
 help on the function by simply including the name as an argument to help.
diff -r 90f8d12f1964 -r 21c3e1370b82 scripts/ChangeLog
--- a/scripts/ChangeLog	Wed Jan 19 04:10:26 2011 -0500
+++ b/scripts/ChangeLog	Wed Jan 19 05:05:07 2011 -0500
@@ -1,3 +1,7 @@
+2011-01-19  John W. Eaton  <jwe@octave.org>
+
+	* help/help.m: New option --list.
+
 2011-01-19  John W. Eaton  <jwe@octave.org>
 
 	* io/strread.m: Avoid PCRE-ism in regexp.  Bug #32066.
diff -r 90f8d12f1964 -r 21c3e1370b82 scripts/help/help.m
--- a/scripts/help/help.m	Wed Jan 19 04:10:26 2011 -0500
+++ b/scripts/help/help.m	Wed Jan 19 05:05:07 2011 -0500
@@ -18,16 +18,21 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Command} {} help @var{name}
+## @deftypefn {Command} {} help @code{--list}
 ## Display the help text for @var{name}.
-## If invoked without any arguments, @code{help} displays instructions
+## If invoked without any arguments, @code{help} display instructions
 ## on how to access help from the command line.
-## 
+##
 ## For example, the command @kbd{help help} prints a short message
 ## describing the @code{help} command.
-## 
+##
+## Given the single argument @code{--list}, list all operators,
+## keywords, built-in functions, and loadable functions available
+## in the current session of Octave.
+##
 ## @deftypefnx {Function File} {@var{text} =} help (@var{name})
 ## Return the help text for the function, @var{name}.
-## 
+##
 ## 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}.
@@ -56,6 +61,16 @@
 
   elseif (nargin == 1 && ischar (name))
 
+    if (strcmp (name, "--list"))
+      tmp = do_list_functions ();
+      if (nargout == 0)
+        printf ("%s", tmp);
+      else
+        retval = tmp;
+      endif
+      return;
+    endif
+
     ## Get help text
     [text, format] = get_help_text (name);
     
@@ -94,6 +109,34 @@
 
 endfunction
 
+function retval = do_list_functions ()
+
+  operators = sprintf ("*** operators:\n\n%s\n\n",
+                       list_in_columns (__operators__ ()));
+
+  keywords = sprintf ("*** keywords:\n\n%s\n\n",
+                      list_in_columns (__keywords__ ()));
+
+  builtins = sprintf ("*** builtins:\n\n%s\n\n",
+                      list_in_columns (__builtins__ ()));
+
+  dirs = strsplit (path, pathsep);
+  flist = "";
+  for i = 2:numel (dirs)
+    files = sort ({dir(fullfile (dirs{i}, "*.m")).name, ...
+                   dir(fullfile (dirs{i}, "*.oct")).name, ...
+                   dir(fullfile (dirs{i}, "*.mex")).name});
+
+    if (! isempty (files))
+      flist = sprintf ("%s*** functions in %s:\n\n%s\n\n",
+                       flist, dirs{i}, list_in_columns (files));
+    endif
+  endfor
+
+  retval = cstrcat (operators, keywords, builtins, flist);
+
+endfunction
+
 function do_contents (name)
 
   found = false;