Re: Cleaning up @deftypefn classes in documentation

[Carnë Draug]

On 12 November 2013 15:01, Rik <address@hidden> wrote:
> On 11/11/2013 08:22 PM, Carnë Draug wrote:
>> 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:
>>>>>>> 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 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.
>>>
>>> [...]
>>>
>>  Was there ever a final decision on this?
>
> We decided on #1, but not just yet.  The complication is that jwe would
> like to have a preface line at the top of any 'help fcn' output which
> identifies where the function is coming from, say the name of the
> particular package.  We could do this by just changing the first line of
> the help text for each function, but of course that is a lot of work.  It
> should be possible using some regular expressions and some modifications,
> maybe to get_first_help_sentence, to extract the package name from one of
> the package files like packinfo.

'help fcn' already says where the function comes from (its path). It's
the very first line displayed. To distinguish between functions coming
from Octave core, a package or something else in the users path... I
don't know.

But currently, the first argument to @deftypfn also doesn't give that
information so can I start removing the "Function File" or "Loadable
Function" from the documentation at least for some packages? And leave
it as empty field (like often happens for the second argument which is
meant for the output) in the mean time, getting rid of clutter being
displayed?

Carnë