Re: package .info documentation and GUI

[Mike Miller]

On Tue, Jun 24, 2014 at 16:32:09 +0200, Olaf Till wrote:
> On Mon, Jun 23, 2014 at 02:50:56PM +0200, Olaf Till wrote:
>> Hi,
>>
>> I'd like to move some lengthy documentation for functions of the optim
>> package into a file in .info format for better structuring. This is
>> possible since `doc ("some_package_function")' makes `info' load a
>> file `doc.info' in the directory of `some_package_function' and
>> display its index entry for "some_package_function".
>>
>> But this does not seem to work with the GUI (Octave-3.8.0), where `doc
>> ("some_package_function")' displays Octaves native documentation.
>
> Same with current gui-release revision (fc0f3b6c37a9, 23/06/2014,
> 22:06).
>
>> Is there an alternative approach for viewing package .info files for
>> the GUI?
>
> seemingly not ...
>
> Maybe the possibility to display package documentation in .info format
> should be an issue for the coming GUI release?

I'm interested in this topic, glad you brought it up. Info
documentation for packages definitely needs some work, and with the
GUI obviously more so. The GUI currently has its own doc browser that
reads Info-format files, but intercepts the doc function before it
gets to the logic to determine which Info file to browse. It also has
issues reading compressed Info files, where on the command line the
GNU info program has no problem.

> But maybe there should be a decision before on what to implement,
> possibly improving what currently can be done with `doc()' in
> octave-cli for packages? Currently, the name of a package function can
> be given as argument to `doc()', causing `info' to load the `doc.info'
> file in the functions directory and to display the functions
> info-node. Problems with this for packages are:
>
> 1. If you want to see basic information for the whole package (in the
>    top node), or just information in info-nodes different from
>    info-nodes of package-functions, it can only be indirectly reached
>    by first calling the documentation of a package-function and then
>    navigating away from the functions info-node.

True, you have to "doc function" for some function in the package.
Maybe a "pkg doc" subcommand could bring up the top node?

> 2. The packages functions are possibly in two different directories
>    (binary and scripted), so you could end up with two different
>    `doc.info' files, and maintaining basic information for the whole
>    package as well as info-nodes for all particular functions is not
>    cleanly possible.

Yes absolutely. In fact, some packages (e.g. geometry) have m-files
organized into subdirectories all added to the path, and I think
doc.info would have to be in each one of those paths, correct?

> This could be improved by
>
> for 2.: putting the packages info-file to a fixed location (as
>         e.g. the packages `doc/' directory) which does not depend on
>         the directory of a package function, and

Yes, that could help. I don't have a way to check at the moment, but
aren't all top-level directories other than "inst" and "src" in a
package installed and kept as is?

>         in accordance with Matlab
>         
> (http://www.mathworks.de/de/help/matlab/ref/doc.html?searchHighlight=doc),
>         allowing the syntax
>
>           `doc ("<package-name>.<function-name>")' .
>
>         (Matlab allows also `doc ("<class-name>.<method-name>")'. It's
>         not clear what to do if a package has the same name as a
>         class, but this issue can probably be dealt with later.)

I think both of these are referring to classdef-style classes and
namespaces (the Java meaning of the word "package"). So I don't think
this syntax helps with Octave's concept of loadable packages and we
probably don't want to conflict with the usage for classdef as that is
being implemented now for Octave 4.2.

One more issue, with my Debian hat on, is that distributions may want
to install all Info documentation in a different directory such as
/usr/share/info, and they may want to compress it. So let's say the
file you want to call "doc.info" is now called "octave-optim.info.gz"
and is installed in /usr/share/info. What else can we do to make it
easier for distributions to install the Info manual according to their
standards and still support the doc function in the Octave shell?

-- 
mike