how to view the texinfo for a package

[Carlo de Falco-3]

Hi,

Some forge packages (very few actually) ship a .info manual which gets installed with the package.
The examples that I could find are odepkg (which I am trying to fix) and communtications.
In the communications package the manual is installed as

  <packages home>/communications-<version number>/doc/comms.info

but I cannot find a way to visualize it within Octave, I tried the following

  doc communications
  doc comms
  doc comms.info

but none of them seems to work.

The current version of odepkg installs the info manual as

  <packages home>/odepkg-<version number>/doc.info

and the only way I found to access it in Octave was to type

  doc doc.info

but this isn't really easy to find out and does not really seem
the right way to go.

My question is:
 
 is the ability of packages to offer an info manual a supported feature of the
 Octave package manager?

 if it is, what is the expected way to access it?

 if it isn't, does it really make sense to ship such manual with those packages?

thanks,
c.

 

[Mike Miller-4]

On Sun, Sep 03, 2017 at 19:05:25 +0200, c. wrote:
> Some forge packages (very few actually) ship a .info manual which gets installed with the package.
> The examples that I could find are odepkg (which I am trying to fix) and communtications.

The optim package includes a function "optim_doc" that solves this
problem its own way.

Take a look at #44529 [1] for some initial ideas about making the doc
function aware of packages. I think it would be a good thing if the doc
function knew whether a function was part of a package and could look
into the appropriate info file if a package provides one.

[1]: https://savannah.gnu.org/bugs/?44529

--
mike

[Carlo de Falco-2]

> On 3 Sep 2017, at 21:11, Mike Miller <[hidden email]> wrote:
>
> On Sun, Sep 03, 2017 at 19:05:25 +0200, c. wrote:
>> Some forge packages (very few actually) ship a .info manual which gets installed with the package.
>> The examples that I could find are odepkg (which I am trying to fix) and communtications.
>
> The optim package includes a function "optim_doc" that solves this
> problem its own way.
>
> Take a look at #44529 [1] for some initial ideas about making the doc
> function aware of packages. I think it would be a good thing if the doc
> function knew whether a function was part of a package and could look
> into the appropriate info file if a package provides one.
>
> [1]: https://savannah.gnu.org/bugs/?44529

I am quite sure that, for odepkg, until some time ago in the past, typing
"doc odepkg" would open the package info manual.

Do you or anyone else know, when or how this changed?

> --
> mike

c.

[Mike Miller-4]

On Sun, Sep 03, 2017 at 21:00:19 +0000, Carlo De Falco wrote:
> I am quite sure that, for odepkg, until some time ago in the past, typing
> "doc odepkg" would open the package info manual.
>
> Do you or anyone else know, when or how this changed?

No, I don't remember that ever working. I see that doc.m looks for a
file called doc.info in the directory containing a matching function
file, but nothing based on the package name.

I think that some logic should be put in place to associate an info file
with the pkg metadata, so for example "doc ode78" would be directed to
the info file associated with odepkg.

We could also add support for pkg names at the same time.

I don't know enough about the GUI info browser to know if it supports
browsing multiple info files, or if it would need some work as well.

--
mike

[Carlo de Falco-2]

> On 3 Sep 2017, at 23:32, Mike Miller <[hidden email]> wrote:
>
> No, I don't remember that ever working. I see that doc.m looks for a
> file called doc.info in the directory containing a matching function
> file, but nothing based on the package name.

Indeed, that is the approach that was used in odepkg!
The package contains an m-file function "odepkg.m" for
documenting the whole package and a file named "doc.info"
that gets installed in the same directory.

"doc odepkg" used to show the contents of "doc.info" but
now it shows the docstring from the m-file instead.

> I think that some logic should be put in place to associate an info file
> with the pkg metadata, so for example "doc ode78" would be directed to
> the info file associated with odepkg.

actually that would be the default behaviour as ode78.m and odepkg.m
are installed in the same directory so doc.info would be in the same directory
as ode78.m.

The logic would probably be required for .oct files though.

c.