Re: Cleaning up @deftypefn classes in documentation

[Rik]

On 07/12/2013 10:55 AM, Carnë Draug wrote:
> On 10 July 2013 18:49, Rik <address@hidden> wrote:
>> The Command form would be used only when the function works for all
>> different input combinations in the command form.  If there is a single
>> situation where it doesn't then the Function keyword would be used.
> This would mean that a function can only have one type of usage which
> is not true.
Yes.  I pointed out earlier that distinction between command and function
isn't absolute since any function can be called in the command form. 
Therefore, this was a way of distinguishing between them.  See below as well.
>  Those values are arguments for deftypefn and deftypefnx
> not to the function. For example, I have recently documented an usage
> of colormap() of the Command style so its help text shows both
> "Function File" and "Command".
You can have both, but I don't like the output it produces in fixed width
environments because columns are no longer aligned.  Take for example 'dbstop',

 -- Built-in Function: RLINE = dbstop ("FUNC")
 -- Built-in Function: RLINE = dbstop ("FUNC", LINE)
 -- Built-in Function: RLINE = dbstop ("FUNC", LINE1, LINE2, ...)

which could be written as

 -- Command: RLINE = dbstop "FUNC"
 -- Built-in Function: RLINE = dbstop ("FUNC", LINE)
 -- Built-in Function: RLINE = dbstop ("FUNC", LINE1, LINE2, ...)
 
but then I find it difficult to see what is changing between one invocation
and the next.

I think the documentation will be too messy if we document that every
function with no arguments can be called in the command form as well as the
function form.  I would rather make a subsection of the documentation on
calling conventions where we explain the general rule about using/not-using
parentheses to invoke a function and what it means for the class of the
input argument.

--Rik