Re: Documentation

[Søren Hauberg]

John W. Eaton wrote:
> On 10-Jul-2005, Søren Hauberg wrote:
>
> | A thing that's always been bugging me, is that I can't add a new info 
> | file for the functions give people. That means all my documentation goes 
> | into the "help function_name" part of each function, which doesn't work 
> | very well when your documentation is long.
>
> There is nothing preventing you from creating a manual for your
> package that looks like the Octave manual and that is built the same
> way, by automatically inserting the docstrings for individual
> functions at appropriate places in your main text.
But it wouldn't be integrated with Octave, right? I wouldn't be able to 
do a "help -i my_function"? So if I create a new package the 
documentation that comes with the package wouldn't be integrated with 
Octave.

> | This is not a perfect solution, since if the user is reading 
> | documentation for a 3rd party package, she will not be able to go 
> | directly to documentation for other packages or for the functions 
> | supplied with Octave (I'm assuming you can only open one .info at a time)
>
> The Texinfo format supports links from one manual to another.  So you
> can link to the documentation for another package or the main Octave
> manual.
Great!

> | On the other hand, then this would be better than the current situation, 
> | and it would allow Octave to support different kinds of formats. (As you 
> | might be able to tell, I'm not that fond of the info format, as it isn't 
> | very good at displaying math).
>
> It is not good for displaying math on a text terminal, but what is?
> OTOH, you have the full power of TeX available for the printed
> version, so it seems that it should be sufficient for most purposes.
> It would also be possible to do better for bitmap displays than for
> text terminals.  The important thing about info is that it is a simple
> format that keeps the structure of the document clean.
I'm not trying to get away from info, it seems to work great. I just 
want to be able to access more graphical documentation from the Octave 
prompt. In matlab terminologi I would like to have a "doc" function. 
This could simply access HTML documentation (or some other graphical 
format, that supports linking).

> | P.S. This is a little bit related, so I'll mention it here. I wanted to 
> | see how good html documentation could be auto-generated from the current 
> | documentation. I've put my first results online at 
> | http://hauberg.org/octavedoc/audio/doc.html
> | It's far from parfect, but I haven't spend much time looking at it.
>
> How did you make the conversion?  What was the original format?
I used the .texi files in doc/interpreter. I then used a combination of 
info2html and latex2html. The "see also"'s doesn't work at the moment, 
but it shouldn't be to hard.
> jwe

/Søren