Re: package .info documentation and GUI

[Olaf Till]

On Tue, Jun 24, 2014 at 05:05:09PM -0400, Mike Miller wrote:
> 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:
> > <snip>
> > 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?

Sounds good, see below.

> > 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?

Yes, AFAICS.

> > 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?

According to pkg/private/copy_files.m, this is not so, but the
toplevel "doc" directory is copied explicitely to under the systems
directory with the packages machine-independent files.

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

You're right, I didn't see the relation of Matlabs "packages" to
classes.

> 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?

pkg() could install the packages info file under `octave_config_info
("infodir")', the latter being configurable for Octave and possibly
altered for Octave packaged by a distribution. Thus packages installed
by the user with pkg() (of packaged Octave) and from the distribution
will put their info files into the same directory. To find the file
again in its installation directory, the filename must follow a
convention (probably as in your example,
"octave-<package-name>.info.gz") and there should indeed be only one
info file per package (which seems reasonable). pkg() should also add
a link in the `dir' file in `octave_config_info ("infodir")'. I'd say
pkg() should compress the packages info file unconditionally, if it
isn't already compressed.

Yes, we could use pkg() also to display the package info. This way we
avoid the possibility of future syntax incompatibility of doc() with
Matlab. But I'd suggest to support an additional option for displaying
the node of an index entry in the file (which may or may not
correspond to a package function); top-node if this option is not
given.

Olaf

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

signature.asc
Description: Digital signature