Documentation

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation

Søren Hauberg
Hi,
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.

I've been thinking a bit about this today, since I think packages should
be able to provide detailed documentation. So I suggest the following:

Extra documentation (in info, html, docbook, whatever) for functions in
directory "DIR" into "DIR/doc/doc.FORMAT", where "FORMAT" is "info",
"html", or whatever format the documentation uses.

For functions supplied with Octave the "DIR/doc/doc.info" could be a
symlink to the info file currently being shipped 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)

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

This change should be fairly easy to implement, but should it be
implemented?

/Søren

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.

Reply | Threaded
Open this post in threaded view
|

Documentation

John W. Eaton-6
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.

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

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

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

jwe

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Bill Denney
In reply to this post by Søren Hauberg
On Sun, 10 Jul 2005, Søren Hauberg wrote:

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

I like the way that this looks.  It would be nice to have this
auto-generated and added to the main octave website for each version of
octave (look at perldoc.perl.org for what I think would be a good way to
make it look).

A couple of things about the formatting:

In IE, the main title of the page (i.e. "Audio Processing") is clipped
because it appears that the words are pushed to the left of the margin (I
see half of the u then "dio Processing").

Also in IE, choosing a different page (like choosing "Finance" in the drop
down menu) doesn't move to the page.

Bill

--
"If you live to be 100, I want to live to be 100 minus one day, so I
never have to live without you."
   -- Winnie the Pooh

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

John W. Eaton-6
On 13-Jul-2005, Bill Denney wrote:

| I like the way that this looks.  It would be nice to have this
| auto-generated and added to the main octave website for each version of
| octave (look at perldoc.perl.org for what I think would be a good way to
| make it look).

It is possible to convert automatically from Texinfo to HTML.

| A couple of things about the formatting:

The current output may not be so good, but that could be corrected.
We are currently using texi2html to convert Octave's documentation to
HTML, but I think we should consider switching to makeinfo now.  Back
in the day, makeinfo did not do a very good job of generating HTML
output, but that seems to be fixed, and the output can be customized
using a CSS file.  So it should be relatively simple to improve the
appearance of the generated files.

jwe

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Søren Hauberg
In reply to this post by John W. Eaton-6
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

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Søren Hauberg
In reply to this post by Bill Denney
Bill Denney wrote:

> On Sun, 10 Jul 2005, Søren Hauberg wrote:
>
>> 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.
>
>
> I like the way that this looks.  It would be nice to have this
> auto-generated and added to the main octave website for each version of
> octave (look at perldoc.perl.org for what I think would be a good way to
> make it look).
>
> A couple of things about the formatting:
>
> In IE, the main title of the page (i.e. "Audio Processing") is clipped
> because it appears that the words are pushed to the left of the margin
> (I see half of the u then "dio Processing").
>
> Also in IE, choosing a different page (like choosing "Finance" in the
> drop down menu) doesn't move to the page.
I don't have access to IE (why would I :-) ) so I can't really test it.
The issues are related to IE not supporting CSS and JavaScript properly.
Since I'm just messing about, I'll need a bit of pushing before I'll fix
IE problems.

>
> Bill
>
/Søren

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

John W. Eaton-6
In reply to this post by Søren Hauberg
On 15-Jul-2005, Søren Hauberg wrote:

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

Currently this is probably true because Octave only looks in one file
when doing a help -i search.  But we can always fix Octave if it does
not do the correct thing.

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

Please try using a current version of makeinfo to generate the HTML
and then write a .css file that gives the appearance you want.  I
think this has the potential for much better and more reliable results
than any other kind of conversion because makeinfo should be able to
correctly parse all the Texinfo markup.

jwe

Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Søren Hauberg
John W. Eaton wrote:

> On 15-Jul-2005, Søren Hauberg wrote:
>
> | 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.
>
> Currently this is probably true because Octave only looks in one file
> when doing a help -i search.  But we can always fix Octave if it does
> not do the correct thing.
This was what I was trying to say in my original post, but since english
isn't my first language, this message properly got lost in translation.

A way to support this would be to generate an info file at startup (or
the first time in the session help -i is called) that links to the
installed info files. Packages would then need a way of telling Octave
that they provide an info file.

Another way to support this would be if the user asks for "help -i
some_function", where "some_function" lives in the directory DIR, let
Octave check if an info file called DIR/doc.info (or something similar)
exist. If it does, then Octave should use that file, if not Octave
should the default info file.

> | 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.
>
> Please try using a current version of makeinfo to generate the HTML
> and then write a .css file that gives the appearance you want.  I
> think this has the potential for much better and more reliable results
> than any other kind of conversion because makeinfo should be able to
> correctly parse all the Texinfo markup.
I tried playing with makeinfo 4.7 (the latest is 4.8, I'll have a look
at it later on). The problem is that I can't seem to make makeinfo
generate math (either MathML of images). texi2html can call latex2html
and have it generate images for math contents. So makeinfo isn't quite
as good as texi2html. Since one should be able to generate MathML from
TeX, I guess it shouldn't be to big a task to include MathML within the
Octave manual (wrapped in @ifhtml).


 > jwe
/Søren