[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
## Re: so many functions not documented...

**From**: |
Paul Kienzle |

**Subject**: |
Re: so many functions not documented... |

**Date**: |
Tue, 7 Sep 2004 20:02:47 -0400 |

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
-------------------------------------------------------------