Re: Cleaning up @deftypefn classes in documentation

[Carnë Draug]

On 12 July 2013 19:32, Rik <address@hidden> wrote:
> 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.

My suggestion was that while it is true that functions accepting only
strings can be called both way, each was designed with the idea to be
called that way. For example, the functions help, citation and news vs
strcmp, strjoin and regexp. So my suggestion was to follow the
"spirit" of the function which I'm guessing is a bit subjective.

Anyway, my new suggestion is, why don't we just ignore the first
argument to deftypen? They have no impact other than distinguishing
things between operators, built-in, loadable and m files. For
operators, no one needs to be told that they are reading about an
operator. I don't think that we should point out the difference
between the other three. For example, imfinfo appears as a m-file and
help with tell you that  but in truth, the work is all done by a
loadable function. And the really built-in functions are already
marked as such on the first line of the help command:

octave> help numel
'numel' is a built-in function from the file libinterp/corefcn/data.cc

And even if that line was not there, why should the help command be
exposing that detail to the user?

So I say, let's just ditch that argument that takes up so much space
on the help text and too often breaks the usage example in 2 lines.

Carnë