Improve "help all"

[Vladimir Prus <vladimir at codesourcery dot com>]

Hi,
at the moment gdb's "help all" command is not as helpful as it could be 
because:

1. It's not mentioned in the output of "help".
2. The output of "help all" lacks any structure -- like visual grouping by 
classes.
3. The prefix commands are printed in weird order. For example, the
"append" and "append binary" commands are printed a couple of screens apart.

This patch fixes all that, and also mentions "apropos" in the output 
of "help".

OK?

- Volodya

	* commands.h (enum command_class): Use different
	values for class_deprecated and class_run.
	* cli/cli-decode.c: (print_help_for_command): New.
	(apropos_cmd): Use the above.
	(help_list): Mention 'help all'
	and 'apropos' when printing top-level help.
	(help_all): Print the class name before printing
	commands in that class.  Don't print prefix commands
	here, instead pass recurse flag to help_cmd_list.
	Print list of unclassified commands at the end.
	(help_cmd_list): When recursing, use all_commands class.
	Recurse only if the class of the command matches.

Index: command.h
===================================================================
RCS file: /cvs/src/src/gdb/command.h,v
retrieving revision 1.54
diff -u -r1.54 command.h
--- command.h	17 Dec 2005 22:33:59 -0000	1.54
+++ command.h	27 Oct 2006 19:39:27 -0000
@@ -30,7 +30,7 @@
 enum command_class
 {
   /* Special args to help_list */
-  class_deprecated, all_classes = -2, all_commands = -1,
+  class_deprecated = -3, all_classes = -2, all_commands = -1,
   /* Classes of commands */
   no_class = -1, class_run = 0, class_vars, class_stack,
   class_files, class_support, class_info, class_breakpoint, class_trace,
Index: cli/cli-decode.c
===================================================================
RCS file: /cvs/src/src/gdb/cli/cli-decode.c,v
retrieving revision 1.58
diff -u -r1.58 cli-decode.c
--- cli/cli-decode.c	17 Dec 2005 22:40:17 -0000	1.58
+++ cli/cli-decode.c	27 Oct 2006 19:39:28 -0000
@@ -46,6 +46,11 @@
 					  int *nfound);
 
 static void help_all (struct ui_file *stream);
+
+static void
+print_help_for_command (struct cmd_list_element *c, char *prefix, int recurse,
+			struct ui_file *stream);
+
 
 /* Set the callback function for the specified command.  For each both
    the commands callback and func() are set.  The latter set to a
@@ -687,14 +692,8 @@
 	  returnvalue=re_search(regex,c->name,strlen(c->name),0,strlen(c->name),NULL);
 	  if (returnvalue >= 0)
 	    {
-	      /* Stolen from help_cmd_list. We don't directly use
-	       * help_cmd_list because it doesn't let us print out
-	       * single commands
-	       */
-	      fprintf_filtered (stream, "%s%s -- ", prefix, c->name);
-	      print_doc_line (stream, c->doc);
-	      fputs_filtered ("\n", stream);
-	      returnvalue=0; /*Set this so we don't print it again.*/
+	      print_help_for_command (c, prefix, 
+				      0 /* don't recurse */, stream);
 	    }
 	}
       if (c->doc != NULL && returnvalue != 0)
@@ -702,13 +701,8 @@
 	  /* Try to match against documentation */
 	  if (re_search(regex,c->doc,strlen(c->doc),0,strlen(c->doc),NULL) >=0)
 	    {
-	      /* Stolen from help_cmd_list. We don't directly use
-	       * help_cmd_list because it doesn't let us print out
-	       * single commands
-	       */
-	      fprintf_filtered (stream, "%s%s -- ", prefix, c->name);
-	      print_doc_line (stream, c->doc);
-	      fputs_filtered ("\n", stream);
+	      print_help_for_command (c, prefix, 
+				      0 /* don't recurse */, stream);
 	    }
 	}
       /* Check if this command has subcommands */
@@ -845,6 +839,9 @@
 			cmdtype1);
       wrap_here ("");
       fprintf_filtered (stream, "that class.");
+
+      fprintf_filtered (stream, "\n\
+Type \"help all\" for the list of all commands.");
     }
 
   fprintf_filtered (stream, "\nType \"help%s\" followed by %scommand name ",
@@ -855,6 +852,8 @@
   fputs_filtered ("full ", stream);
   wrap_here ("");
   fputs_filtered ("documentation.\n", stream);
+  fputs_filtered ("Type \"apropos word\" to search "
+		  "for commands related to \"word\".\n", stream);		    
   fputs_filtered ("Command name abbreviations are allowed if unambiguous.\n",
 		  stream);
 }
@@ -864,19 +863,41 @@
 {
   struct cmd_list_element *c;
   extern struct cmd_list_element *cmdlist;
+  int seen_unclassified = 0;
 
   for (c = cmdlist; c; c = c->next)
     {
       if (c->abbrev_flag)
         continue;
-      /* If this is a prefix command, print it's subcommands */
-      if (c->prefixlist)
-        help_cmd_list (*c->prefixlist, all_commands, c->prefixname, 0, stream);
-    
       /* If this is a class name, print all of the commands in the class */
-      else if (c->func == NULL)
-        help_cmd_list (cmdlist, c->class, "", 0, stream);
+
+      if (c->func == NULL)
+	{
+	  fprintf_filtered (stream, "\nCommand class: %s\n\n", c->name);
+	  help_cmd_list (cmdlist, c->class, "", 1, stream);
+	}
     }
+
+  /* While it's expected that all commands are in some class,
+     as a safety measure, we'll print commands outside of any
+     class at the end.  */
+
+  for (c = cmdlist; c; c = c->next)
+    {
+      if (c->abbrev_flag)
+        continue;
+
+      if (c->class == no_class)
+	{
+	  if (!seen_unclassified)
+	    {
+	      fprintf_filtered (stream, "\nUnclassified commands\n\n");
+	      seen_unclassified = 1;
+	    }
+	  print_help_for_command (c, "", 1, stream);
+	}
+    }
+
 }
 
 /* Print only the first line of STR on STREAM.  */
@@ -909,6 +930,26 @@
   ui_out_text (uiout, line_buffer);
 }
 
+/* Print one-line help for command C.
+   If RECURSE is non-zero, also print one-line descriptions
+   of all prefixed subcommands. */
+static void
+print_help_for_command (struct cmd_list_element *c, char *prefix, int recurse,
+			struct ui_file *stream)
+{
+  fprintf_filtered (stream, "%s%s -- ", prefix, c->name);
+  print_doc_line (stream, c->doc);
+  fputs_filtered ("\n", stream);
+  
+  if (recurse
+      && c->prefixlist != 0
+      && c->abbrev_flag == 0)
+    /* Subcommands of a prefix command typically have 'all_commands'
+       as class.  If we pass CLASS to recursive invocation,
+       most often we won't see anything. */
+    help_cmd_list (*c->prefixlist, all_commands, c->prefixname, 1, stream);
+}
+
 /*
  * Implement a help command on command list LIST.
  * RECURSE should be non-zero if this should be done recursively on
@@ -932,20 +973,14 @@
   struct cmd_list_element *c;
 
   for (c = list; c; c = c->next)
-    {
+    {      
       if (c->abbrev_flag == 0 &&
 	  (class == all_commands
 	   || (class == all_classes && c->func == NULL)
 	   || (class == c->class && c->func != NULL)))
 	{
-	  fprintf_filtered (stream, "%s%s -- ", prefix, c->name);
-	  print_doc_line (stream, c->doc);
-	  fputs_filtered ("\n", stream);
+	  print_help_for_command (c, prefix, recurse, stream);
 	}
-      if (recurse
-	  && c->prefixlist != 0
-	  && c->abbrev_flag == 0)
-	help_cmd_list (*c->prefixlist, class, c->prefixname, 1, stream);
     }
 }