Re: Requirements for releasing the STK toolbox as an Octave forge package ?

[Carnë Draug]

On 24 February 2014 15:40, Julien Bect <address@hidden> wrote:
> On 24/02/2014 16:06, Carnë Draug wrote:
>>
>> On 24 February 2014 14:48, Julien Bect <address@hidden> wrote:
>>>>>
>>>>> Is there any way I can preview the HTML documentation formatted as it
>>>>> will be formatted on the Octave Forge website ?
>>>>
>>>> You will need to download the CSS style file [1]. Maybe some of the
>>>> javascript files will be needed. Carnė [1]
>>>> http://octave.sourceforge.net/octave-forge.css
>>>
>>> Ok. But how do I generate the HTML output ? Should I use the
>>> generate_package_html () function from the "generate_html" package ?
>>>
>>> I have tried this, after installing STK as an octave package :
>>>
>>>      pkg load generate_html
>>>      generate_package_html ("stk", "stk_html", "octave-forge")
>>>
>>> but it doesn't work for me : only the M-files located at the root at the
>>> package seem to be found. How do I produce documentation for a package
>>> that
>>> has several subdirectories ?
>>
>> That should work if you have the stk package installed. I created the
>> stk package as you mentioned to try to duplicate this but I couldn't
>> even load the package. When I did it (pkg load stk), it prints the GPL
>> notice a *lot* of times, before giving the following error repeated
>> too many times:
>>
>> error:   clear at line 30, column 5
>> error:   /home/carandraug/octave/stk-2.2.0/stk_init.m at line 72, column
>> 67
>> error:   /home/carandraug/octave/stk-2.2.0/PKG_ADD at line 4, column 1
>
>
> Installing and loading the package works fine for me (both on the 3.6.4
> release that comes with my Ubuntu 13.04, and on my fresh build of Octave
> 3.8.1-rc3). Which release of Octave are you using ?

I'm using 3.8.0.

> Could you please try to step through stk_init.m to understand why it is
> called several times ?

I found the problem. the problem is when stk_init calls clear which is
modified on my side to, among other things, reload packages. Because
of this, it gets stuck into a loop reloading the stk package.

Reverting my local changes to clear, I could load it correctly. While
you remove most of the temporary variables, it seems your script
forgets two of them "STK_SKIP_BUILDMEX" and "mole_dir"

>> Also, why do you have the functions split into multiple directories?
>> If you are already creating the package with a script, there's no need
>> for organization, you might as well place all the m files into a
>> single directory. This will also make it simpler for you, and will be
>> less prone to bugs when adding and removing to the search path.
>
>
> As a user, I prefer when I can browse the source tree and understand from
> its structure how the toolbox/package/module/... is organized. So, yes, I
> know that I could put everything into a single directory, but I would really
> prefer to keep the original layout if possible (I see that the LTFAT package
> has subdirectories, for instance, so it shouldn't be a problem).
>
> Plus, the packaging script would be more delicate to write, since not
> everything must be flattened out (for instance, we have private
> subdirectories, class subdirectories, and even class subdirectories that
> contain private subdirectories that contain MEX-files...).
>
> Of course, if it turns out that this is the only to make it work, I will do
> that.

I know other packages do it and they all have that reason. I still
always advise against it. Managing path manually is a pain and likely
to cause unexpected problems. And if Octave ever changes how it
manages packages internally, it will suddenly break. You are relying
on things which, albeit stable, are undocumented and not meant to be
used.

>> By the way, the package is shadowing the following core functions:
>> linsolve, qunatile, and corr. Why is it doing this?
>
>
> It's not shadowing anything : the error message that you quote is
> inaccurate...
>
> The functions that you mention are provided for compatibility with older
> versions of Octave (for instance, 3.2.4 has neither corr nor linsolve) and
> to avoid a dependency on the Statistics toolbox for Matlab users. They are
> only added to the path if it is detected at runtime that they are missing
> (see misc/mole/PKG_ADD.m).
>
> I will remove them during the installation if it is detected that they are
> not needed...

This is what I get when I install the package
http://bpaste.net/show/WaA1RPB6zuIYx0wwXbGB/

I found the problem why generate_html is not working for you. There is
no INDEX file. When it is missing, it will create one automatically
from the directories where it placed the functions. Since the
functions are not where they are supposed anymore (m files at the root
of the package and oct in a directory named with API version), pkg did
not found them.

Also, the way you move the mex files into the same directory as m
files is not recommended. Downstream packages are unlikely to be happy
about it, since architecture dependent files are supposed to be kept
separated.

Carnë