and idea for the development of Scipad

[Torbjørn Pettersen]

François Vogel skrev:
> 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.
Hi François
I think all your points are valid.

It doesn't make much sense to use help_from_sci() if one later intends 
to edit the xml help file.
My idea is that documentation could be written and maintained as part 
of  the head_comment section of the .sci file, and that help_from_sci 
should be used for generation of the final xml files. This would 
eliminate any sync issues.

In terms of arguments for adding another help related function to Scilab 
I'm on very thin ice, especially since I was not aware of the 
"head_comments" function :-)
So adding yet another help function is not something I will argue for.
If one wants to include some of the functionality from help_from_sci 
into Scilab on a permanent basis, my suggestion is to merge the 
functionality into the existing help_skeleton function. This would avoid 
any new functions being introduced.

>
>
> 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.
This sounds interesting. I'll take a look at the tcl files. It could be 
a nice feature to add to the toolbox.
>
> 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 for the response - and not least for providing Scipad and Scilab!

Regards,
-Torbjørn.

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.scilab.org/pipermail/dev/attachments/20080929/d006f74c/attachment.htm>