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

[Oliver Heimlich]

On 26.04.2015 18:57, Julien Bect wrote:
> 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.

Yes, this perfectly works.

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

This is exactly what I was looking for. I gave it a try with my early 
manual draft and everything works out of the box.

> 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 don't need that kind of feature and the optim_doc.m code looks like it 
could be handled more general by the pkg or doc command in GNU Octave core.

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

Very helpful, indeed. I am going to focus on the HTML documentation for 
Octave Forge then. Users as well as downstream distributors can do 
whatever they need with the Texinfo sources.

Oliver