Re: Cleaning up @deftypefn classes in documentation

[Carnë Draug]

On 7 August 2013 23:50, Rik <address@hidden> wrote:
> On 08/07/2013 07:46 AM, Carnë Draug wrote:
>> 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?
> 8/7/13
>
> The two proposals on the table are:
>
> 1) Drop the first field entirely, or perhaps use it to indicate the
> Octave-Forge package to which the function belongs.
>   Pros: Frees up lots of visual room onscreen when using 'help fcn'
>   Cons: Have to use 'which (fcn)' to find out whether function is M-file,
> Built-in, or Dynamically Loaded.
>
> 2) Drop 'Mapper Function' and 'Command'.  Use first field to indicate
> M-File, Built-in, or Dynamically Loaded function.
>   Pros: Indication of function speed in help.  Indication of where to go
> looking for more information
>   Cons: Longer, verbose help entries.  Still need to use 'which (fcn)' to
> find exact file location.  Speed indication is only approximate.
>
> jwe shouldn't have to be the arbiter on everything, but this seems like a
> big enough change that I'd like him to give the final blessing on a strategy.
>
> --Rik

 Was there ever a final decision on this?

Carnë