[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Documentation

From: Søren Hauberg
Subject: Re: Documentation
Date: Fri, 15 Jul 2005 15:33:05 +0200
User-agent: Mozilla Thunderbird 1.0.2 (X11/20050404)

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

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]