Re: Cleaning up @deftypefn classes in documentation

[Rik]

On 07/12/2013 02:59 PM, Carnë Draug wrote:
> 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.
Interesting suggestion.  I also dislike how much space the identification
takes at the start of the documentation.

In the interests of being thorough, let's step back and consider what we
might want to use this field for.  It is a free parameter and we could
leave it blank or we could use it to provide something useful to the reader
of the documentation.  Right now we're not particularly happy with the
strings we are putting in there.  Can people on the mailing list think of
something that would be useful to use here?

--Rik