# HG changeset patch
# User Rik <rik@octave.org>
# Date 1411248330 25200
# Node ID d4a920d2824273a790de6a04df0fe11b5f6d0d42
# Parent  fa48651fbb8ab62486dc82e8b412bd8750d2e242
Depecrate usage() function.


* NEWS: Announce deprecation.

* error.cc (F__usage__): Rename usage to internal name __usage__.

* scripts/deprecated/usage.m: New function to wrap C++ __usage__ function.

* scripts/deprecated/module.mk: Add usage.m to build system.

* errors.txi: Remove usage() from manual.

diff -r fa48651fbb8a -r d4a920d28242 NEWS
--- a/NEWS	Sat Sep 20 17:16:56 2014 -0400
+++ b/NEWS	Sat Sep 20 14:25:30 2014 -0700
@@ -90,11 +90,13 @@
     be removed from Octave 4.6 (or whatever version is the second major
     release after 4.2):
 
-      bicubic
-      find_dir_in_path
-      nargchk
-      nfields
-      syl
+      Function           | Replacement
+      -------------------|------------------
+      bicubic            | interp2
+      find_dir_in_path   | dir_in_loadpath
+      nfields            | numfields
+      usage              | print_usage
+      syl                | sylvester
 
     The following functions were deprecated in Octave 3.8 and have been
     removed from Octave 4.2.
diff -r fa48651fbb8a -r d4a920d28242 doc/interpreter/errors.txi
--- a/doc/interpreter/errors.txi	Sat Sep 20 17:16:56 2014 -0400
+++ b/doc/interpreter/errors.txi	Sat Sep 20 14:25:30 2014 -0700
@@ -126,8 +126,6 @@
 
 @DOCSTRING(print_usage)
 
-@DOCSTRING(usage)
-
 @DOCSTRING(beep)
 
 @DOCSTRING(beep_on_error)
diff -r fa48651fbb8a -r d4a920d28242 libinterp/corefcn/error.cc
--- a/libinterp/corefcn/error.cc	Sat Sep 20 17:16:56 2014 -0400
+++ b/libinterp/corefcn/error.cc	Sat Sep 20 14:25:30 2014 -0700
@@ -1921,7 +1921,7 @@
   return retval;
 }
 
-DEFUN (usage, args, ,
+DEFUN (__usage__, args, ,
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} usage (@var{msg})\n\
 Print the message @var{msg}, prefixed by the string @samp{usage: }, and\n\
diff -r fa48651fbb8a -r d4a920d28242 scripts/deprecated/module.mk
--- a/scripts/deprecated/module.mk	Sat Sep 20 17:16:56 2014 -0400
+++ b/scripts/deprecated/module.mk	Sat Sep 20 14:25:30 2014 -0700
@@ -7,7 +7,8 @@
   deprecated/nargchk.m \
   deprecated/nfields.m \
   deprecated/strmatch.m \
-  deprecated/syl.m
+  deprecated/syl.m \
+  deprecated/usage.m
 
 FCN_FILES += $(deprecated_FCN_FILES)
 
diff -r fa48651fbb8a -r d4a920d28242 scripts/deprecated/usage.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/deprecated/usage.m	Sat Sep 20 14:25:30 2014 -0700
@@ -0,0 +1,66 @@
+## Copyright (C) 2014 John W. Eaton
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Built-in Function} {} usage (@var{msg})
+##
+## @code{usage} is deprecated and will be removed in Octave version 4.6.
+## Please use @code{print_usage} in all new code.
+##
+## Print the message @var{msg}, prefixed by the string @samp{usage: }, and
+## set Octave's internal error state such that control will return to the
+## top level without evaluating any more commands.  This is useful for
+## aborting from functions.
+## 
+## After @code{usage} is evaluated, Octave will print a traceback of all
+## the function calls leading to the usage message.
+## 
+## You should use this function for reporting problems errors that result
+## from an improper call to a function, such as calling a function with an
+## incorrect number of arguments, or with arguments of the wrong type.  For
+## example, most functions distributed with Octave begin with code like
+## this
+## 
+## @example
+## @group
+## if (nargin != 2)
+##   usage (\"foo (a, b)\");
+## endif
+## @end group
+## @end example
+## 
+## @noindent
+## to check for the proper number of arguments.
+## @seealso{print_usage}
+## @end deftypefn
+
+## Deprecated in version 4.2
+
+function retval = usage (varargin)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "usage is obsolete and will be removed from a future version of Octave, please use print_usage instead");
+  endif
+
+  retval = __usage__ (varargin{:});
+
+endfunction
+