print_usage changes

[John W. Eaton]

Up until now, we have used (for example)

  print_usage ("svd");

in functions defined in C++, but something like

  usage ("[n, s] = weekday (d, [form])");

in scripting language functions.  This means duplication of
information in the script files since the help text usually contains a
line (or lines) like

  @deftypefn {Function File} address@hidden, @var{s}] =} weekday (@var{d}, 
address@hidden)

which could be used to generate the usage message.

Also up until now, the internal print_usage function would display the
entire help text for the function, which I know some people found
annoying.

Even having to specify the function name in the print_usage call is
less than ideal since it means duplicating some information about the
current function.  It would be better to not have to supply the
function name and leave it to the print_usage function to find the doc
string for the current function and then format the @def... portion of
the text.  So I've modified the internal print_usage function to do
that and produce output like this

  octave:1> svd

  Invalid call to svd.  Correct usage is:

   -- Loadable Function: S = svd (A)
   -- Loadable Function: [U, S, V] = svd (A)


If the help text doesn't look like Texinfo or no @def... commands are
found, then the full text of the doc string is displayed as before.

To avoid breaking external code, we still have the function

  void print_usage (const std::string&);

but the argument is ignored and it is tagged with GCC_ATTR_DEPRECATED
so you'll get a warning about it if you use it and you are compiling
with GCC.

In addition, I made the print_usage function accessible to the
scripting language.  If (for example) the usage message in the
weekday.m file is replaced by

  print_usage ();

then incorrect usage of weekday will result in the following message:

  octave:1> weekday

  Invalid call to weekday.  Correct usage is:

   -- Function File: [N, S] = weekday (D, [FORM])


For consistency, I'd like to make all the usage messages in Octave use
this new form.  I've already converted all the C++ code.   It would be
helpful if a few volunteers could help with this task by working
through all the current script files and replacing the calls to
"usage" (or disp, fprintf, etc., in perhaps a few cases) with
print_usage.  It would probably be best to submit a separate patch for
each subdirectory in the script directory tree.  If you are interested
in helping with this project, please let me know so we can coordinate
the effort.

Also, I have a patch to update all the Octave Forge C++ functions.
Should I check it in?

Thanks,

jwe