Re: Documentation style

[Rik]

On 09/24/2014 12:23 PM, John W. Eaton wrote:
> On 09/23/2014 11:53 AM, Rik wrote:
>> On 09/12/2014 09:00 AM, address@hidden wrote:
>
>>  > Do people prefer the current way of listing all the possibilities?
>> I'm working on adding the zoom function and if documented this way,
>> there will be 10 lines enumerating the different ways it can be called.
>>  >
>>  > Also, why distinguish between Command and Function File now that any
>> function that accepts character string arguments can be called with
>> "command" syntax?
>>  >
>>
>> The verbosity is a good thing, in my opinion.  The idea is based on two
>> tenets: 1) that people want to use a function quickly, and 2) the human
>> brain is adept at pattern matching.  The way I visualize this Human
>> Interface Design challenge is that the user's problem is a pegboard.
>> They know that function XXX can solve the problem (put the peg in the
>> hole) but they have to match the shape of the function (square,
>> triangle, circle) to their particular problem (square, triangle, circle).
>
> OK, this is fine with me.
>
>> As for {Command} versus {Function File}, we have plans to actually
>> eliminate that field entirely.  The discussions happened a while ago,
>> but maybe we'll get around to implementing it sometime.
>
> I'd be OK to remove that now.  It should be easy to do automatically in
> the Octave sources.  The only question I have is whether it would be
> better to wait until just before the next stable release so that we don't
> cause unnecessary trouble for people who might send patches relative to
> sources in some released version.  But maybe it would be better to just
> go ahead and do it.  Where?  Stable or gui-release?
>

I'd say gui-release, and then stop accepting docstring changes on stable. 
This shouldn't be a problem as it doesn't happen very often anyways, and
we're almost done with the 3.8.X stable branch anyways.

--Rik