Re: package .info documentation and GUI

[Olaf Till]

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?

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.

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.

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

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


for 1.: extending Matlabs syntax and its interpretation:

          doc ("<package-name>.")

        could display the top-level node of the packages info-file,
        and

          doc ("<package-name>.<index-entry>")

        could display a node corresponding to an arbitrary entry in
        the info-files index, not necessarily corresponding to a
        particular package function.

The latter extension is in accordance with the current interpretation
of `doc ("<index-entry>")' for core Octave documentation.

Olaf

-- 
public key id EAFE0591, e.g. on x-hkp://pool.sks-keyservers.net

signature.asc
Description: Digital signature