Re: octave html help

[Paul Kienzle]

Excellent questions.

I'm glad somebody finds the categorical index, since
Albert Danial and I put a lot of effort went into constructing it.

To generate the index from octave-forge, you need the
DOCSTRINGS files from octave.  These are not available
unless you build octave from scratch, so I haven't put it as
a build step.  Instead I call admin/make_index periodically
and upload the resulting index.  It turns out I don't delete it
after uploading, so it is still there as:

        http://octave.sourceforge.net/index.tar.gz

I've added a link.

Anybody with skills in web design is welcome to improve
the look of the page.  All the html is automatically generated,
so it is just a matter of changing make_index so that it
generates something prettier.  pdf output would also be
nice.

Other docs are not built as part of the octave-forge build process,
such as the coda docs.  You can build these by going into the
coda subdirectory and typing make (at least you can on recent
CVS versions).  Anyone is welcome to contribute patches to
the build system to make all the docs and install them in the
appropriate place.  In addition to the compatibility docs in
doc, there are other docs sprinkled throughout the hierarchy.

The test harness in octave-forge/extra/testfun also supplies
demo and example functions.  For any file containing
        %!demo
        %!  octave demo code
you can type 'demo fn' and it will display the example code
and run the example.  Type 'example fn' to just see the
example.  You can even have multiple examples for each file.
So far only 53 functions out of more than 450 in octave forge
have examples provide, so there is plenty of opportunity for
the community to make contributions.

octave-forge does not have much in the way of overview
documents describing the functions available in the various
toolboxes.   Done properly, these would be textbooks in
the various subject areas.   You might start with a set of
course notes available on the web, or even better, you
might link to relevant wikipedia articles, and write your
own if none exist.

octave-forge is the community development branch of
the octave project.  It grew out of our frustration at having
no place to post our contributions where others could
make use of them and improve them.

Sometimes functions move from octave-forge to octave,
particularly if the function exists in basic matlab.  If you
see a function that you think belongs in octave, then first
make sure that the documentation is adequate and uses
texinfo format, and that it has a complete set of tests.  You
can then send mail to octave-maintainers explaining
why that particular function should be part of octave.

In addition to octave-forge, we need the equivalent of
CPAN where people can post their own toolboxes
even if they are too specialized for inclusion in
octave-forge.  Before this can happen someone needs
to work on a packaging system so that
building/testing/installing is consistent amongst packages.

Paul Kienzle
address@hidden

On Feb 11, 2004, at 5:49 PM, Jonathan Stickel wrote:

> I do have octave-forge installed (via gentoo emerge).  No html files
> came with it; just the standard text documents:
> ...
> My (limited) understanding of octave vs. octave-forge amounts to this
> analogy:  octave <-> matlab; octave-forge <-> matlab-toolboxes.
>
> Documentation is something else altogether.  In both matlab and octave
> you can get help from the command prompt by:
>
> octave> help foo
>
> This requires knowing that "foo" exists, and at times the help you get
> here is quite limited.  Recent Matlab products (which I no longer use)
> come with extensive html based documentation that was browsable and
> searchable.  The browsable index of functions on octave.sourceforge
> seems to be a primative form of this, but still very useful.  This is
> what I want available locally.



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