[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation style
From: |
Rik |
Subject: |
Re: Documentation style |
Date: |
Wed, 24 Sep 2014 15:37:50 -0700 |
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