[REPOST] patch: command deprecator

[David Whedon <davidw at gordian dot com>]

I cleaned up my patch, deleted worthless lines, etc. thanks for the
suggestions Elena. I may not have found all missing gnu-isms, but I gave
it a shot. I do wonder what the thinking is as far as keeping things
looking the same within one file, i.e K & R style functions for most, but
new ones standard.

I want to make a few quick notes about why I chose to do this the way that
I did, so things make a bit of sense, and also so that someone can find a
better way if they want, and it also will help those looking at the logic
of what I did.

I decided that I wanted the warning to print out the full command name,
for example:
(gdb) set end b
Warning: command 'set endian big' is deprecated.
Use 'bigendian'.
(gdb)

At the time the command 'big' is called, we only have that command name
"big".  I thought that a warning message: 
Warning: command 'big' is deprecated.

would be confusing. Also:
Warning: command 'set end b' is deprecated.

looks somewhat dumb.

I found that I needed therefore to decode the command
line in order to figure out what the actual command name was.  This is
because postfix commands (don't know of a better name, I mean the ones
that come after prefix commands) don't retain any knowledge of their
prefix command. If they did, then we could simply lookup the prefixname on
the prefix command, and we would be set.  I don't see an easy way of
adding that info since when a command is added it is added to a list, and
that list doesn't have any knowledge of the commands that are using it
(the list) as a prefixlist (I'd call it a postfixlist).

This led me to write lookup_cmd_composition which is admittedly an
iterative version of lookup_cmd_1.  The recursive version can't work (as
far as I can tell) with what I am trying to do because we need to know
both the command that is going to be executed _and_ its prefix command.

In addition, I wanted to be able to deprecate aliases alone. That is,
deprecate the alias and not the command.

Tests were done on i686-pc-linux-gnu.

Test results before:

		=== gdb Summary ===

# of expected passes		6356
# of unexpected failures	13
# of expected failures		200
# of unresolved testcases	3


Test results after, I added about 10 new tests that test the deprecator:

		=== gdb Summary ===

# of expected passes		6368
# of unexpected failures	13
# of expected failures		200
# of unresolved testcases	3


And now, here comes the patch:


1999-02-22 David Whedon <dwhedon@gordian.com>

	* top.c (execute_command): checks all commands beore executing
	to see if the user needs to be warned that the command is
	deprecated, warns user if appropriate.
	(add_info), (add_info_alias), (add_com) , (add_com_alias): changed
	return values from void to struct cmd_list_element *.

	* command.c (lookup_cmd_1): check aliases before following link 
	in case user needs to be warned about a deprecated alias.
	(deprecate_cmd): new exported function for command deprecation,
	sets flags and posibly a replacement string.
	(deprecated_cmd_warning): new exported funciton to warn user about
	a deprecated command. 
	(lookup_cmd_composition): new exported function that determines
	alias, prefix_command, and cmd based on a string.  This is useful
	is we want to full name of a command.

	* command.h : added prototypes for deprecate_cmd,
	deprecated_warn_user and lookup_cmd_composition, added flags to
	the cmd_list_element structure, changed return values for
	add_com_* and add_info_* from void to cmd_list_element.

	* maint.c : (maintenance_deprecate): new function to deprecate a
	command.  This exists only so that the testsuite can deprecate
	commands at runtime and check the warning behavior.
	(maintenance_undeprecate) : new function, drops deprecated flags.
	(maintenance_do_deprecate): actually does the (un)deprecation.
	(initialize_maint_cmds): added the above new deprecate commands.

	* gdbint.texinfo : added paragraph about command deprecation.
	
	* commands.exp : added command deprecator tests.

Generating diff
Index: gdb/command.c
===================================================================
RCS file: /cvs/src/src/gdb/command.c,v
retrieving revision 1.2
diff -c -3 -p -r1.2 command.c
*** command.c	2000/02/09 08:52:45	1.2
--- command.c	2000/02/23 05:15:03
*************** add_cmd (name, class, fun, doc, list)
*** 108,113 ****
--- 108,115 ----
    c->class = class;
    c->function.cfunc = fun;
    c->doc = doc;
+   c->flags = 0;
+   c->replacement = NULL;
    c->hook = NULL;
    c->prefixlist = NULL;
    c->prefixname = NULL;
*************** add_cmd (name, class, fun, doc, list)
*** 125,130 ****
--- 127,159 ----
    return c;
  }
  
+ 
+ /* Deprecates a command CMD.
+    REPLACEMENT is the name of the command which should be used in place
+    of this command, or NULL if no such command exists.
+ 
+    This function does not check to see if command REPLACEMENT exists
+    since gdb may not have gotten around to adding REPLACEMENT when this
+    function is called.
+ 
+    Returns a pointer to the deprecated command.  */
+ 
+ struct cmd_list_element *
+ deprecate_cmd (cmd, replacement)
+      struct cmd_list_element *cmd;
+      char *replacement;
+ {
+   cmd->flags |= (CMD_DEPRECATED | DEPRECATED_WARN_USER);
+ 
+   if(replacement != NULL)
+     cmd->replacement = replacement;
+   else
+     cmd->replacement = NULL;
+   
+   return cmd;
+ }
+ 
+ 
  /* Same as above, except that the abbrev_flag is set. */
  
  #if 0				/* Currently unused */
*************** lookup_cmd_1 (text, clist, result_list, 
*** 645,650 ****
--- 674,680 ----
    char *p, *command;
    int len, tmp, nfound;
    struct cmd_list_element *found, *c;
+   char *line=*text;
  
    while (**text == ' ' || **text == '\t')
      (*text)++;
*************** lookup_cmd_1 (text, clist, result_list, 
*** 716,724 ****
  
    /* If this was an abbreviation, use the base command instead.  */
  
!   if (found->cmd_pointer)
      found = found->cmd_pointer;
! 
    /* If we found a prefix command, keep looking.  */
  
    if (found->prefixlist)
--- 746,756 ----
  
    /* If this was an abbreviation, use the base command instead.  */
  
!   if (found->cmd_pointer){
!     if(found->flags & DEPRECATED_WARN_USER)
!       deprecated_cmd_warning(&line);
      found = found->cmd_pointer;
!   }
    /* If we found a prefix command, keep looking.  */
  
    if (found->prefixlist)
*************** lookup_cmd (line, list, cmdtype, allow_u
*** 896,901 ****
--- 928,1153 ----
      }
    return 0;
  }
+ 
+ /*
+   We are here presumably because an alias or command in *TEXT is 
+   deprecated and a warning message should be generated.  This function
+   decodes *TEXT and potentially generates a warning message as outlined
+   below.
+ 
+   Example for 'set endian big' which has a fictitious alias 'seb'.
+   
+   If alias wasn't used in *TEXT, and the command is deprecated:
+   "warning: 'set endian big' is deprecated." 
+ 
+   If alias was used, and only the alias is deprecated:
+   "warning: 'seb' an alias for the command 'set endian big' is deprecated."
+ 
+   If alias was used and command is deprecated (regardless of whether the
+   alias itself is deprecated:
+   
+   "warning: 'set endian big' (seb) is deprecated."
+ 
+   After the message has been sent, clear the appropriate flags in the
+   command and/or the alias so the user is no longer bothered.
+ 
+  */
+ void
+ deprecated_cmd_warning (char **text)
+ {
+   struct cmd_list_element *alias=NULL, *prefix_cmd=NULL, *cmd=NULL;
+   struct cmd_list_element *c;
+   char *type;
+  
+   lookup_cmd_composition(text, &alias, &prefix_cmd, &cmd);
+ 
+   if ( !( (alias ? (alias->flags & DEPRECATED_WARN_USER) : 0) 
+ 	  || (prefix_cmd ? (prefix_cmd->flags & DEPRECATED_WARN_USER) : 0) 
+ 	  || (cmd ? (cmd->flags & DEPRECATED_WARN_USER) : 0) ) 
+        || !cmd )
+     /* If nothing deprecated, and no 'cmd', we bail. */
+     return;
+   
+   /* is there a prefix cmd? if so, that is the one which could
+      be either a set or show, otherwise check cmd. Is this always true? */
+   if(prefix_cmd==NULL)
+     c=cmd;
+   else
+     c=prefix_cmd;
+   
+   if(c->type==not_set_cmd)
+     type=NULL;
+   else if(c->type==set_cmd)
+     type="set ";
+   else if(c->type==show_cmd)
+     type="show ";
+   else
+     type=NULL;
+   
+   printf_filtered("Warning:");
+ 
+   if(alias && !(c->flags & CMD_DEPRECATED))
+     printf_filtered(" '%s', an alias for the", alias->name);
+ 
+   printf_filtered(" command '%s", (type ? type : ""));
+   
+   if(prefix_cmd)
+     printf_filtered("%s", prefix_cmd->prefixname);
+   
+   printf_filtered("%s", cmd->name);
+ 
+   if(alias && (c->flags & CMD_DEPRECATED))
+     printf_filtered("' (%s) is deprecated.\n", alias->name);
+   else
+     printf_filtered("' is deprecated.\n"); 
+   
+ 
+   /* if it is only the alias that is deprecated, we want to indicate the
+      new alias, otherwise we'll indicate the new command */
+ 
+   if(alias && !(c->flags & CMD_DEPRECATED))
+     {
+       if(alias->replacement)
+ 	printf_filtered ("Use '%s'.\n\n",alias->replacement);
+       else
+ 	printf_filtered ("No alternative known.\n\n");
+     }  
+   else
+     {
+       if(cmd->replacement)
+ 	printf_filtered ("Use '%s'.\n\n",cmd->replacement);
+       else
+ 	printf_filtered ("No alternative known.\n\n");
+     }
+ 
+   /* We've warned you, now we'll keep quiet */
+   if(alias)
+     alias->flags &= ~DEPRECATED_WARN_USER;
+   
+   cmd->flags &= ~DEPRECATED_WARN_USER;
+ }
+ 
+ 
+ 
+ /*
+   Look up the contents of *LINE as a command in the command list 'cmdlist'
+   and set *alias, *prefix_cmd and *cmd as specific below:
+   
+   alias : if *LINE refers to an alias, set *alias to point to that command.
+ 
+   prefix_cmd : if the command whose execution is specified by *LINE is a 
+   postfix command (i.e. one that is preceeded by a prefix command) set 
+   *prefix_cmd.
+ 
+   *cmd : the command that *LINE refers to.
+ 
+   If any of *alias, *prefix_cmd, or *cmd cannot be determined or do not 
+   exist, they are set to NULL.
+ 
+  */
+ void
+ lookup_cmd_composition (char **text, 
+ 			struct cmd_list_element **alias,
+ 			struct cmd_list_element **prefix_cmd, 
+ 			struct cmd_list_element **cmd)
+ {
+   char *p, *command;
+   int len, tmp, nfound;
+   struct cmd_list_element *cur_list;
+   struct cmd_list_element *prev_cmd=NULL;
+   *alias = NULL;
+   *prefix_cmd = NULL;
+   *cmd = NULL;
+   
+   cur_list=cmdlist;
+   
+   while(1)
+     { 
+       /* Go through as many command lists as we need to 
+ 	 to find the command TEXT refers to. */
+       
+       prev_cmd=*cmd;
+       
+       while (**text == ' ' || **text == '\t')
+ 	(*text)++;
+       
+       /* Treating underscores as part of command words is important
+ 	 so that "set args_foo()" doesn't get interpreted as
+ 	 "set args _foo()".  */
+       for (p = *text;
+ 	   *p && (isalnum (*p) || *p == '-' || *p == '_' ||
+ 		  (tui_version &&
+ 		   (*p == '+' || *p == '<' || *p == '>' || *p == '$')) ||
+ 		  (xdb_commands && (*p == '!' || *p == '/' || *p == '?')));
+ 	   p++)
+ 	;
+       
+       /* If nothing but whitespace, return.  */
+       if (p == *text)
+ 	break;
+       
+       len = p - *text;
+       
+       /* *text and p now bracket the first command word to lookup (and
+ 	 it's length is len).  We copy this into a local temporary */
+       
+       command = (char *) alloca (len + 1);
+       for (tmp = 0; tmp < len; tmp++)
+ 	{
+ 	  char x = (*text)[tmp];
+ 	  command[tmp] = x;
+ 	}
+       command[len] = '\0';
+       
+       /* Look it up.  */
+       *cmd = 0;
+       nfound = 0;
+       *cmd = find_cmd (command, len, cur_list, 1, &nfound);
+       
+       /* 
+       ** We didn't find the command in the entered case, so lower case it
+       ** and search again.
+       */
+       if (!*cmd || nfound == 0)
+ 	{
+ 	  for (tmp = 0; tmp < len; tmp++)
+ 	    {
+ 	      char x = command[tmp];
+ 	      command[tmp] = isupper (x) ? tolower (x) : x;
+ 	    }
+ 	  *cmd = find_cmd (command, len, cur_list, 1, &nfound);
+ 	}
+       
+       if(*cmd == (struct cmd_list_element *) -1)
+ 	{
+ 	  *alias = NULL;
+ 	  *prefix_cmd = NULL;
+ 	  *cmd = NULL;      
+ 	  return; /* ambiguous */
+ 	}
+       
+       if (*cmd == NULL)
+ 	break;
+       else
+ 	{
+ 	  if ((*cmd)->cmd_pointer)
+ 	    {
+ 	      *alias=*cmd;
+ 	      *cmd = (*cmd)->cmd_pointer;
+ 	    }
+ 	  *prefix_cmd=prev_cmd;
+ 	}
+       if ((*cmd)->prefixlist)
+ 	cur_list = *(*cmd)->prefixlist;
+       else
+ 	break;
+       
+       *text=p;
+     }
+ }
+ 
+ 
+ 
  
  #if 0
  /* Look up the contents of *LINE as a command in the command list LIST.
Index: gdb/command.h
===================================================================
RCS file: /cvs/src/src/gdb/command.h,v
retrieving revision 1.1.1.4
diff -c -3 -p -r1.1.1.4 command.h
*** command.h	2000/02/02 00:21:05	1.1.1.4
--- command.h	2000/02/23 05:15:03
*************** struct cmd_list_element
*** 115,120 ****
--- 115,127 ----
         Entire string should also end with a period, not a newline.  */
      char *doc;
  
+     int flags;
+ #define CMD_DEPRECATED            0x1
+ #define DEPRECATED_WARN_USER      0x2
+ 
+     /* if this command is deprecated, this is the replacement name */
+     char *replacement;
+ 
      /* Hook for another command to be executed before this command.  */
      struct cmd_list_element *hook;
  
*************** extern struct cmd_list_element *
*** 208,224 ****
    lookup_cmd_1 PARAMS ((char **, struct cmd_list_element *,
  			struct cmd_list_element **, int));
  
  extern void
  add_com PARAMS ((char *, enum command_class, void (*fun) (char *, int),
  		 char *));
  
! extern void
  add_com_alias PARAMS ((char *, char *, enum command_class, int));
  
! extern void
  add_info PARAMS ((char *, void (*fun) (char *, int), char *));
  
! extern void
  add_info_alias PARAMS ((char *, char *, int));
  
  extern char **
--- 215,243 ----
    lookup_cmd_1 PARAMS ((char **, struct cmd_list_element *,
  			struct cmd_list_element **, int));
  
+ extern struct cmd_list_element *
+ deprecate_cmd (struct cmd_list_element *, char * );
+ 
  extern void
+ deprecated_cmd_warning (char **);
+ 
+ extern void
+ lookup_cmd_composition (char **text,
+ 			struct cmd_list_element **alias,
+ 			struct cmd_list_element **prefix_cmd,
+ 			struct cmd_list_element **cmd);
+ 
+ extern struct cmd_list_element *
  add_com PARAMS ((char *, enum command_class, void (*fun) (char *, int),
  		 char *));
  
! extern struct cmd_list_element *
  add_com_alias PARAMS ((char *, char *, enum command_class, int));
  
! extern struct cmd_list_element *
  add_info PARAMS ((char *, void (*fun) (char *, int), char *));
  
! extern struct cmd_list_element *
  add_info_alias PARAMS ((char *, char *, int));
  
  extern char **
Index: gdb/maint.c
===================================================================
RCS file: /cvs/src/src/gdb/maint.c,v
retrieving revision 1.1.1.7
diff -c -3 -p -r1.1.1.7 maint.c
*** maint.c	1999/09/08 23:59:19	1.1.1.7
--- maint.c	2000/02/23 05:15:03
*************** maintenance_translate_address (arg, from
*** 358,363 ****
--- 358,466 ----
    return;
  }
  
+ 
+ static void
+ maintenance_deprecate (char *args, int from_tty)
+ {
+   char *demangled;
+   
+   if (args == NULL || *args == '\0')
+     {
+       printf_unfiltered ("\"maintenance deprecate\" takes an argument, \n\
+ the command you want to deprecate, and optionally the replacement command \n\
+ enclosed in quotes.\n");
+     }
+   
+   maintenance_do_deprecate(args, 1);
+ 
+ }
+ 
+ 
+ static void
+ maintenance_undeprecate (char *args, int from_tty)
+ {
+   char *demangled;
+ 
+   if (args == NULL || *args == '\0')
+     {
+       printf_unfiltered ("\"maintenance undeprecate\" takes an argument, \n\
+ the command you want to undeprecate.\n");
+     }
+   
+   maintenance_do_deprecate(args, 0);
+   
+ }
+ 
+ /*  
+     You really shouldn't be using this. It is just for the testsuite.
+     It leaks memory.  
+ 
+     The reason it leaks is that I can't tell if the replacement
+     command name is created by malloc, or its space was set aside at 
+     compile time.  Since I don't want to risk freeing something that 
+     can't be free'd, I don't free a thing.  Let me know if you see a
+     solution to this.
+ 
+     This function deprecated a command and optionally assigns it an 
+     replacement.
+     
+ */
+ 
+ static void maintenance_do_deprecate(char *text, int deprecate){
+ 
+   struct cmd_list_element *alias=NULL, *prefix_cmd=NULL, *cmd=NULL;
+   char *start_ptr, *end_ptr;
+   int len;
+   char *replacement;
+ 
+ 
+   if(deprecate)
+     {
+       /* look for a replacement command */
+       if(start_ptr = strchr(text, '\"'))
+ 	{
+ 	  start_ptr++;
+ 	  if(end_ptr = strrchr(start_ptr, '\"'))
+ 	    {
+ 	      len = end_ptr-start_ptr;
+ 	      replacement = malloc(len);
+ 	      strncpy(replacement, start_ptr,len);
+ 	      replacement[len]='\0';
+ 	    }
+ 	  else
+ 	    replacement = NULL;
+ 	}
+       else
+ 	replacement = NULL;
+     }
+   
+   
+   lookup_cmd_composition(&text, &alias, &prefix_cmd, &cmd);
+   
+   /* if they used an alias, we only want to deprecate the alias */
+   if(alias)
+     {
+       if(deprecate)
+ 	alias->flags |= (DEPRECATED_WARN_USER | CMD_DEPRECATED);
+       else
+ 	alias->flags &= ~(DEPRECATED_WARN_USER | CMD_DEPRECATED);
+       alias->replacement=replacement;
+       return;
+     }
+   else if(cmd)
+     {
+       if(deprecate)
+ 	cmd->flags |= (DEPRECATED_WARN_USER | CMD_DEPRECATED);
+       else
+ 	cmd->flags &= ~(DEPRECATED_WARN_USER | CMD_DEPRECATED);
+       cmd->replacement=replacement;
+       return;
+     }
+   else
+     printf_filtered("Can't find command '%s' to deprecate.\n", text);
+ }
+ 
+ 
  void
  _initialize_maint_cmds ()
  {
*************** If a SOURCE file is specified, dump only
*** 456,461 ****
--- 559,577 ----
  	   "Translate a section name and address to a symbol.",
  	   &maintenancelist);
  
+   add_cmd ("deprecate", class_maintenance, maintenance_deprecate,
+ 	   "Deprecate a command.  Note that this is just in here so the \n\
+ testsuite can check the comamnd deprecator. You probably shouldn't use this,\n\
+ rather you should use the C function deprecate_cmd().  If you decide you \n\
+ want to use it: maintenance deprecate 'commandname' \"replacement\". The \n\ 
+ replacement is optional.", &maintenancelist);
+ 
+   add_cmd ("undeprecate", class_maintenance, maintenance_undeprecate,
+ 	   "Undeprecate a command.  Note that this is just in here so the \n\
+ testsuite can check the comamnd deprecator. You probably shouldn't use this,\n\
+ If you decide you want to use it: maintenance undeprecate 'commandname'", 
+ 	   &maintenancelist);
+ 
    add_show_from_set (
  		      add_set_cmd ("watchdog", class_maintenance, var_zinteger, (char *) &watchdog,
  				   "Set watchdog timer.\n\
*************** finish a low-level step or continue oper
*** 464,466 ****
--- 580,589 ----
  passes without a response from the target, an error occurs.", &setlist),
  		      &showlist);
  }
+ 
+ 
+ 
+ 
+ 
+ 
+ 
Index: gdb/top.c
===================================================================
RCS file: /cvs/src/src/gdb/top.c,v
retrieving revision 1.3
diff -c -3 -p -r1.3 top.c
*** top.c	2000/02/23 00:25:42	1.3
--- top.c	2000/02/23 05:15:03
*************** execute_command (p, from_tty)
*** 1453,1458 ****
--- 1453,1459 ----
    register struct cmd_list_element *c;
    register enum language flang;
    static int warned = 0;
+   char *line;
    /* FIXME: These should really be in an appropriate header file */
    extern void serial_log_command PARAMS ((const char *));
  
*************** execute_command (p, from_tty)
*** 1473,1479 ****
    if (*p)
      {
        char *arg;
! 
        c = lookup_cmd (&p, cmdlist, "", 0, 1);
  
        /* If the target is running, we allow only a limited set of
--- 1474,1481 ----
    if (*p)
      {
        char *arg;
!       line=p;
!       
        c = lookup_cmd (&p, cmdlist, "", 0, 1);
  
        /* If the target is running, we allow only a limited set of
*************** execute_command (p, from_tty)
*** 1496,1506 ****
  	    p--;
  	  *(p + 1) = '\0';
  	}
! 
        /* If this command has been hooked, run the hook first. */
        if (c->hook)
  	execute_user_command (c->hook, (char *) 0);
  
        if (c->class == class_user)
  	execute_user_command (c, arg);
        else if (c->type == set_cmd || c->type == show_cmd)
--- 1498,1511 ----
  	    p--;
  	  *(p + 1) = '\0';
  	}
! 	
        /* If this command has been hooked, run the hook first. */
        if (c->hook)
  	execute_user_command (c->hook, (char *) 0);
  
+       if(c->flags & DEPRECATED_WARN_USER)
+ 	deprecated_cmd_warning(&line);
+ 
        if (c->class == class_user)
  	execute_user_command (c, arg);
        else if (c->type == set_cmd || c->type == show_cmd)
*************** free_command_lines (lptr)
*** 2871,2894 ****
  
  /* Add an element to the list of info subcommands.  */
  
! void
  add_info (name, fun, doc)
       char *name;
       void (*fun) PARAMS ((char *, int));
       char *doc;
  {
!   add_cmd (name, no_class, fun, doc, &infolist);
  }
  
  /* Add an alias to the list of info subcommands.  */
  
! void
  add_info_alias (name, oldname, abbrev_flag)
       char *name;
       char *oldname;
       int abbrev_flag;
  {
!   add_alias_cmd (name, oldname, 0, abbrev_flag, &infolist);
  }
  
  /* The "info" command is defined as a prefix, with allow_unknown = 0.
--- 2876,2899 ----
  
  /* Add an element to the list of info subcommands.  */
  
! struct cmd_list_element *
  add_info (name, fun, doc)
       char *name;
       void (*fun) PARAMS ((char *, int));
       char *doc;
  {
!   return add_cmd (name, no_class, fun, doc, &infolist);
  }
  
  /* Add an alias to the list of info subcommands.  */
  
! struct cmd_list_element *
  add_info_alias (name, oldname, abbrev_flag)
       char *name;
       char *oldname;
       int abbrev_flag;
  {
!   return add_alias_cmd (name, oldname, 0, abbrev_flag, &infolist);
  }
  
  /* The "info" command is defined as a prefix, with allow_unknown = 0.
*************** show_command (arg, from_tty)
*** 2944,2969 ****
  
  /* Add an element to the list of commands.  */
  
! void
  add_com (name, class, fun, doc)
       char *name;
       enum command_class class;
       void (*fun) PARAMS ((char *, int));
       char *doc;
  {
!   add_cmd (name, class, fun, doc, &cmdlist);
  }
  
  /* Add an alias or abbreviation command to the list of commands.  */
  
! void
  add_com_alias (name, oldname, class, abbrev_flag)
       char *name;
       char *oldname;
       enum command_class class;
       int abbrev_flag;
  {
!   add_alias_cmd (name, oldname, class, abbrev_flag, &cmdlist);
  }
  
  void
--- 2949,2974 ----
  
  /* Add an element to the list of commands.  */
  
! struct cmd_list_element *
  add_com (name, class, fun, doc)
       char *name;
       enum command_class class;
       void (*fun) PARAMS ((char *, int));
       char *doc;
  {
!   return add_cmd (name, class, fun, doc, &cmdlist);
  }
  
  /* Add an alias or abbreviation command to the list of commands.  */
  
! struct cmd_list_element *
  add_com_alias (name, oldname, class, abbrev_flag)
       char *name;
       char *oldname;
       enum command_class class;
       int abbrev_flag;
  {
!   return add_alias_cmd (name, oldname, class, abbrev_flag, &cmdlist);
  }
  
  void
Index: gdb/doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.2
diff -c -3 -p -r1.2 gdbint.texinfo
*** gdbint.texinfo	2000/02/22 19:22:25	1.2
--- gdbint.texinfo	2000/02/23 05:15:03
*************** to the @code{set_thread_cmd_list}.
*** 332,339 ****
  
  To add commands in general, use @code{add_cmd}.  @code{add_com} adds to
  the main command list, and should be used for those commands.  The usual
! place to add commands is in the @code{_initialize_@var{xyz}} routines at the
! ends of most source files.
  
  @section Console Printing
  
--- 332,348 ----
  
  To add commands in general, use @code{add_cmd}.  @code{add_com} adds to
  the main command list, and should be used for those commands.  The usual
! place to add commands is in the @code{_initialize_@var{xyz}} routines at
! the ends of most source files. 
! 
! Before removing commands from the command set it is a good idea to
! deprecate them for some time.  Use @code{deprecate_cmd} on commands or
! aliases to set the deprecated flag. The first time a comamnd is used the
! user will be warned and offered a replacement (if one exists). Note that
! the replacement string passed to @code{deprecate_cmd} should be the full
! name of the command, i.e. the entire string the user should type at the
! command line.
! 
  
  @section Console Printing
  
Index: gdb/testsuite/gdb.base/commands.exp
===================================================================
RCS file: /cvs/src/src/gdb/testsuite/gdb.base/commands.exp,v
retrieving revision 1.1.1.5
diff -c -3 -p -r1.1.1.5 commands.exp
*** commands.exp	1999/11/17 02:30:37	1.1.1.5
--- commands.exp	2000/02/23 05:15:04
*************** proc test_command_prompt_position {} {
*** 375,380 ****
--- 375,404 ----
  }
  
  
+ 
+ proc deprecated_command_test {} {
+     
+     
+     gdb_test "maintenance deprecate blah" "Can't find command.*" \
+ 	    "tried to deprecate non-existsing command"
+ 
+     gdb_test "maintenance deprecate bt \"new_bt\"" "" "deprecated bt"
+     gdb_test "bt" "Warning: 'bt', an alias for the command 'backtrace' is deprecated.*Use 'new_bt'.*" "bt deprecated warning, with replacement"
+     gdb_test "bt" "\#0.*" "Deprecated warning goes away"
+ 
+     gdb_test "maintenance deprecate bt \"new_bt\"" "" "deprecated bt"
+     gdb_test "maintenance deprecate backtrace \"new_backtrace\"" "" "deprecated backtrace"
+     gdb_test "bt" "Warning: command 'backtrace' \\(bt\\) is deprecated.*Use 'new_backtrace'.*" "both alias and command are deprecated"
+     gdb_test "bt" "\#0.*" "Deprecated warning goes away"
+ 
+     gdb_test "maintenance deprecate set endian big \"seb\" " "" "deprecate long comamnd"
+     gdb_test "set endian big" "Warning: command 'set endian big' is deprecated.*Use 'seb'.*" "long command deprecated"
+ 
+     gdb_test "maintenance deprecate set endian big" "" "deprecate long comamnd"
+    gdb_test "set endian big" "Warning: command 'set endian big' is deprecated.*No alternative known.*" "long command deprecated with no alternative."
+ }
+ 
+ 
  gdbvar_simple_if_test
  gdbvar_simple_while_test
  gdbvar_complex_if_while_test
*************** breakpoint_command_test
*** 387,393 ****
  user_defined_command_test
  watchpoint_command_test
  test_command_prompt_position
! 
  
  
  
--- 411,417 ----
  user_defined_command_test
  watchpoint_command_test
  test_command_prompt_position
! deprecated_command_test