Re: so many functions not documented...

[Paul Kienzle]

On Sep 7, 2004, at 9:49 AM, Bojan Petkovic wrote:

> Hi everyone,
> I am novice Octave user and trying to figure out how all this GNU 
> things work and would really appreciate some help considerind 
> followind (basic) questions. I am using Octave 2.1.42 installed from 
> complete forge distribution on Win2k. So here it is,
> - How certain function is being accepted to be distributed from 
> official Octave distributors like Octave.org or sf.net.

octave-forge (on sf.net) is very open to accepting new functions.  
Until somebody takes the initiative to set some packaging standards and 
build a CPAN-like archive of octave packages, it's the only central 
archive we've got.

octave (on octave.org) accepts only functions which are formatted and 
documented according to octave standards, and for which John Eaton is 
willing to assume maintenance responsibility.

> - Why some of them are distributed but not documented in octave.info 
> files coming within distribution although they have help header in 
> it's body. For example there are lot of files concerning optimization 
> or numerical integration or splines but they are not documented not 
> only in manual but in .info files too.

The info files come from octave.  Functions on octave-forge are not 
included.  It is also possible that new functions have been added to 
octave, but do not yet have a place-holder in the manual in which shows 
where they should be included.

octave.sf.net has a categorical index of functions which is more 
complete.

The aforementioned packaging standards which haven't been developed yet 
need to include rules for incorporating package level documentation and 
function documentation in the categorical index and in the manual.

> - Why some of distributed files begin for example with "## Copyright 
> (C) 2001 Paul Kienzle", others for example with "## Copyright (C) 
> 1996, 1997 John W. Eaton#### This file is part of Octave" and some 
> without any copyright and/or "This is part of Octave" notification, 
> like m/integration/count.m or crule2d.m etc. Are they official Octave 
> functions, tested by some body and approved etc? and if not why 
> distributed from official distributor?

Functions can have their own independent authors, even in octave.

Only functions included in octave should say 'This file is part of 
Octave'.

Only very short functions (e.g., less than about 5 lines) should be 
distributed without copyright and license. Those which are longer need 
to be marked with some sort of license statement since the default 
under US law (and probably most other places due to WIPO) does not give 
us the right to redistribute.

Many functions are granted to the public domain --- limitations of 
octave help function force us to put the public domain statement below 
the function documentation.

Functions in octave ought to have tests in octave/tests/*.  Functions 
in octave-forge ought to have tests embedded in the function file 
(using %! comments).  Not all octave code paths have associated tests.  
Feel free to send patches.

> - Is it still good and preferable idea to write functions which would 
> have the same name and role as functions in Matlab toolboxes or is 
> Octave now developing toolboxes more like in independent way.

The toolboxes are developed independently.  However, to reduce the 
cognitive burden for those using both systems, and to make it easier to 
share software between systems, we encourage using a similar api for 
similar functionality.  Some toolboxes are more similar than others 
(e.g., signal vs. statistics).  Some toolboxes  (e.g., TSA) are 
designed to run in both octave and matlab.

- Paul



-------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.octave.org
How to fund new projects:  http://www.octave.org/funding.html
Subscription information:  http://www.octave.org/archive.html
-------------------------------------------------------------