From maintainers-request at octave dot org Sun Nov 13 10:37:56 2005
Subject: usage statement on builtin functions
From: "John W. Eaton" <jwe at bevo dot che dot wisc dot edu>
To: Paul Kienzle <pkienzle at users dot sourceforge dot net>
Cc: William Poetra Yoga H <williampoetra at yahoo dot com>,         octave maintainers mailing list <maintainers@octave.org>
Date: Sun, 13 Nov 2005 11:37:50 -0500

On 13-Nov-2005, Paul Kienzle wrote:

| I agree that builtin functions should behave like scripts. However
| I prefer the script behaviour of printing a one-line usage statement
| when functions are used incorrectly rather than dumping a screenful
| of docs.
| 
| Making this change to Octave would require substantial effort, so
| I wouldn't start it before asking John if he agrees.

I prefer the full help text, but how about compromising with a
user-defined setting that allows you to control the output from
the print_usage function?

Currently, we have

  print_usage ("foo");

in built-in functions.  We could recommend the same in scripts.
Normally, print_usage produces something like

  *** svd:

   -- Loadable Function: S = svd (A)
   -- Loadable Function: [U, S, V] = svd (A)
       Compute the singular value decomposition of A

	    a = u * sigma * v'

       The function `svd' normally returns the vector of singular values.
       If asked for three return values, it computes U, S, and V.  For
       example,

       ...

but we could have it optionally produce just the lines

  *** svd:

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


We would need to change all instances of

  usage ("foo (x, y)")

in all Octave's script functions to be

  print_usage ("foo");

but that should be relatively easy to do.

If we fix the problem this way, we get consistency in the built-in and
script behavior and we eliminate the need to edit both the docstrings
and usage messages.

jwe