[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: package .info documentation and GUI
From: |
Olaf Till |
Subject: |
Re: package .info documentation and GUI |
Date: |
Tue, 24 Jun 2014 16:32:09 +0200 |
User-agent: |
Mutt/1.5.21 (2010-09-15) |
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