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


On Nov 13, 2005, at 11:37 AM, John W. Eaton wrote:

> 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.

Yeah, I thought of that shortly after posting.  It would be a matter
of extracting the  at deftypefn commands and formatting them nicely.

One concern is with testing failure conditions.  Here I need a
predictable output pattern to test for in the lasterr string.
It is important that the usage statement not be printed in a
try ... catch context.

I would prefer the usage statement to indicate that there is an error
by printing 'usage:' and I would not want the leading "*** svd:\n\n".
I'm not sure the words "Loadable Function" carry much meaning for
the end user in any case.

Normally I would write the above as:

    usage: S = svd (A)  OR  [U, S, V] = svd (A)

but with really long set of usage statements I would want them
spread over multiple lines.

Not all functions have texinfo documentation that make it easy
to extract the usage statement.  Clever regular expressions could
capture most instances.  Or these functions could continue to
use usage() as they currently do, but the new usage function
should check the full help flag before deciding to print the
summary statement or the full help.

- Paul