Re: Manual for GNU Octave package (Octave-Forge)

[Julien Bect]

Le 26/04/2015 12:32, Oliver Heimlich a écrit :
> The wiki documentation is no longer an advantage and I want the 
> package release to contain a matching documentation (for many 
> different reasons) from now on. I started a doc/manual.texinfo file, 
> which is naturally also going to be in the release tarball. However, 
> the “pkg install” will probably drop it and the user is never going to 
> see the manual. How should I release the manual?

According to

https://www.gnu.org/software/octave/doc/interpreter/Creating-Packages.html#Creating-Packages

the files in doc "will be directly installed in a sub-directory of the 
installed package for future reference."

Look at the control package, for instance. After installation, you 
should find a pdf user manual in doc/control.pdf.


> 1. Should I generate a HTML version of the package manual and include 
> it in the [package]-html.tar.gz for publication on Octave Forge? I 
> could use the HTML template from the generate_html package to get a 
> matching design. I could patch the package's index.html to contain a 
> link to the manual next to the function reference.

There is already a minimal support for the inclusion of a "package 
manual" in the generate_html package.

As an example (hmmm... perhaps the only example ?) you can look at :

http://octave.sourceforge.net/optim/index.html

(see the "Package Documentation" hyperlink on the right).

You can also have a look at the optim_doc.m which provides a direct 
access to the info doc of the optim package from within octave.


I hope this helps (and I'm looking forward to reading what others might 
have to say about this issue).

@++
Julien