Re: Documentation style

[John W. Eaton]

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?

jwe