and idea for the development of Scipad

[François Vogel]

Hi Tobjørn,

Your idea looks interesting to me, thanks for submitting it. I have a 
few comments on this.


At the first place I'm wondering if having your idea implemented in 
Scipad would not provide the user with a feature that few of them will 
use. Is it not too specific? After all, Scilab and Matlab are 
different, and we already have a function head_comments in Scilab.

Also, having documentation of a function in both its header comments 
and in an xml file will sooner or later lead to sync issues between 
these two. For that reason I'm not sure it is desirable.


On the practical side I'm wondering about implementation.

Indeed, the Scipad menu entry "File/Create help skeleton" basically is 
a wrapper around the Scilab function help_skeleton. It is easy to call 
another function instead of help_skeleton. You can see the details in 
proc helpskeleton (in file scilabexec.tcl). Calling help_from_sci 
instead of help_skeleton is straightforward.

However, first of all I would add another entry in the file menu (e.g. 
"File/Create help from function header comments" or something alike), 
rather than replacing the existing entry. Some users would like to 
keep the vanilla help_skeleton perhaps.

Then, function help_from_sci must be known by Scilab. Two ways:

1) check for presence of your contrib to enable or not the new entry 
in the File menu

2) include this function in Scilab

Proposition 2) could be done either by including it in the help module 
(would be the best place I think), or alternatively in the Scipad 
module itself. Licenses to be checked if in help module, no problem in 
scipad module (which is GPL, as your contrib is).

I have not yet looked at help_from_sci more than very cursively, but I 
will soon try it in practice.


As a first step I would like to open the discussion about your 
proposal to other people. That's why I cc the developers mailing list 
on this, I hope you will forgive me to do so without first consulting you.

Some people on the dev list perhaps have basic things to say about it, 
for instance on the principle of having comments in both function 
headers and xml files.

Also, the opteam could state whether they consider your function 
help_from_sci as a feature they could integrate in the help module (if 
you agree, obviously).

Finally, especially Enrico, who is maintaining Scipad with me, may 
have an opinion on this.

Thanks,
Francois


Torbjørn Pettersen said on 28/09/2008 18:28:
> Hi Francois Vogel
> I just noticed a nice feature in your excellent SciPad editor - the File 
> - Create help_skeleton function, which I guess runs the current open 
> file through the help_skeleton function in Scilab.
> 
> I was wondering - is it easy to make Scipad use an alternative function 
> to help_skeleton for the generation of the xml help file?
> 
> The reason I ask is that I have created a modified version of 
> help_skeleton which is based on the idea that help files
> should preferably be written and maintained as part of the scilab source 
> file.
> As a former matlab user I find it annoying to have to maintain both a 
> .sci and a .xml file for every function I write.
> 
> The revised function called help_from_sci, which is part of a recently 
> uploaded toolbox 
> http://www.scilab.org/contrib/index_contrib.php?page=displayContribution&fileID=1145 
> 
> generates a complete .xml help file based on the initial comment section 
> of the .sci source file - much in the same way as matlab does.
> In order to format the .xml file correctly some key words should be used 
> when writing the documentation section.
> If it was possible to run help_from_sci directly from SciPad it would 
> provide a quick verification that the automatically generated xml files 
> looks as intended.
> 
> -Regards
> Torbjørn.
>