Re: Cleaning up @deftypefn classes in documentation

[Rik]

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