Re: Cleaning up @deftypefn classes in documentation

[Carnë Draug]

On 14 July 2013 21:49, Carnë Draug <address@hidden> wrote:
> On 13 July 2013 21:59, Rik <address@hidden> wrote:
>> 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?
>
> The only thing I can see being useful on the help text that is not yet
> displayed (it actually is, for those who can decipher it from the file
> path), is what is providing the function. If the function is part of
> Octave core, from a package, or from somewhere else. But I don't think
> deftypefn is the right place to specify it because:
>
> 1) that's on a per function basis, not per usage;
> 2) it's not elegant. There should be a way to know where the function
> comes from, and have the help function find and show it.

Just bringing up this again. What are we to do about this?

Carnë