[OctDev] listing functions in a package

[c.]

On 18/feb/08, at 15:28, David Bateman wrote:

> c. wrote:
>> On 18/feb/08, at 13:33, David Bateman wrote:
>>
>>
>>> c. wrote:
>>>
>>>> Does the attached patch do what you intended?
>>>>
>>> It fails on the signal package that includes variables in the INDEX
>>> file
>>> like
>>>
>>> <quote>
>>> $SPCTOOLS= in spline directory of Dennis Brown's <a
>>> href="ftp://svr-ftp.eng.cam.ac.uk/pub/comp.speech/tools/
>>> spctools">SPCtools</a>
>>> $TFTB= try <a
>>> href="http://www-isis.enst.fr/Applications/tftb/iutsn.univ-
>>> nantes.fr/auger/tftb.html">Time-Frequency
>>> Tool box</a>
>>>
>>>
>>> signal >> Signal processing
>>> Signals
>>>  diric
>>>  gauspuls
>>>  ...
>>> </quote>
>>>
>>> The function categories are incorrectly probed.. You should scan for
>>> "signal >>" and ignore anything beforehand.. Apart from that it
>>> looks good..
>>>
>>> D.
>>>
>>
>> David,
>>
>> Looking at the INDEX for the signal package I also see lines like:
>>
>> arcov= use <code>ar_covar</code> $SPCTOOLS
>>
>> I was not aware that such things were possible...
>> I see this syntax is explained in the comments to main/INDEX while it
>> is not
>> on the octave-forge website (wouldn't it be worth adding at least a
>> reference
>> to this syntax specification on http://octave.sourceforge.net/
>> developers.html ?).
>>
>> To handle such lines with variable substitution and markup tags will
>> require a bit more
>> logic than expected, I'll look into it.
>> Would a patch that implements just skipping those lines be acceptable
>> for the meantime?
>> After all this syntax is expected to be used for functions that are
>> not implemented in the
>> package, anyway...
>>
>> c.
>>
>> P.S. I see the inline octave documentation (doc pkg) also has a  
>> section
>> describing the syntax of the INDEX file but does not mention variable
>> substitution or markup language.
>>
> These variables are typical to give the user a reference to an
> alternative means of achieving something in Octave that you can  
> achieve
> in Matlab. Therefore its probably better not to use the INDEX files at
> all and use the method you previously used of scanning the *.m  
> *.oct and
> *.mex files.. Though you'll also need to take care of the dispatch
> commands that might be in the PKG_ADD files.
>
> D.
>

After thinking about this for a while I believe that parsing the  
INDEX file is still the way to go...
The INDEX file is optional, if it is not there it is generated  
automatically by scanning the package directory,
so there are two cases:

1) The package developer didn't bother to write  an INDEX, his  
package is just a set of functions that he believes do not need to be  
organized into categories or distinguished one from the other.

in this case the package directory is scanned for a list of functions  
at the time of install (or rebuild) so to get the list of functions  
one can parse the INDEX. If the INDEX is missing or corrupted throw  
an error prompting the user to run 'pkg rebuild'

2) The package developer chose to list only some specific functions  
in the INDEX file and to organize them into categories. In this case  
I think the choice of which functions deserve to be listed should be  
left to the package developer ( non indexed functions may be just for  
internal use for example), so again parsing the INDEX should be the  
correct way to get the list of functions.

The attached patch solves the issue with the hiccup on 'pkg describe  
signal' and implements the behavior described above (which is that  
intended in the previous version).

What do you think about this?
c.

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: pkg_patch.txt
Url: https://www.cae.wisc.edu/pipermail/octave-maintainers/attachments/20080219/f38417d4/attachment-0001.txt 
-------------- next part --------------