[Scilab-Dev] SEP #3 Add of a build documentation function

[Sylvestre Ledru]

> Sylvestre Ledru said on 07/07/2008 18:18:
> > This SEP proposes to add a new Scilab function in order to build
> > Scilab's documentation. The current solution based on sh & DOS batch
> > files is far from being efficient (hardcoded path, duplicate code, needs
> > the Scilab Dev-Tools env...)
> 
> Could you elaborate on what the "current solution" exactly is?
A serie of scripts which call some Java methods/objects to build the
help from XML files given as arg.

> How is it supposed to work right now?
Only with the Scilab Dev-Tools env :/ which makes Scilab impossible to build from scratch with standard packages provided by the distrib.
For example, I don't use Dev-Tools because it is not the way to do it
under GNU/Linux; that means that I cannot build the help for now.

> Do you target perhaps the single command I'm aware of, which is 
> xmltojar()?
> There is also xmltoformat(), but none of them is documented so far, 
> and it's a bit hard to make an accurate idea on how it works.
I must admit that I didn't dig too much into these files.
For now, the objectif of the SEP #3 is to replace
the big select/case calling the script:
output_file = pathconvert(SCI
+"/modules/helptools/jar/scilab_"+getlanguage()+"_help.jar",%f,%f);
log_file    = pathconvert(SCI
+"/modules/helptools/scilab_"+getlanguage()+"_help.jar.log",%f,%f);
script_tool = pathconvert(SCI+"/modules/helptools/bin/sci2jh",%f,%f);
by a built-in Scilab function which will call Java objects.


> For reference, see also a number of tries of mine here:
> http://bugzilla.scilab.org/show_bug.cgi?id=3015#c4
I saw your post. Interesting.
> 
> Besides, a few ideas/comments based on your v1.1 of SEP#3:
> 
> - "the way it has been done causes a serie of strong issues."
> What kind of issues?
Packaging & maintenance issues mainly.

> Are you talking about performance also? You're obviously aware of 
> this, but let's state it: performance of the new process is dramatic 
> wrt Scilab 4 process.
It is not the objective of this SEP but! I will probably have to see how
it works (for example: in order to provide more output!), I will see
where we spend a decade.

>  For me, updating the help files usually takes 
> around an hour per language on a not so old machine. This just kills 
> any good will for updating the help pages.
Hmmm, it is not normal. It should not be that long.

> - "sh and DOS scripts (SCI/modules/helptools/bin/*) are calling Java 
> object with arguments as arguments."
> 
> ?? arguments as arguments? I don't understand.
well, normal :$
I will update that

> - "Therefore, it is pretty straightforward to move this into a Scilab 
> function."
> 
> So, is this SEP about wrapping the existing sh/DOS scripts in unix_g 
> calls? That's already the case I think, that's what is done in 
> xmltoformat, or?
> Or do you mean some built-in (non .sci file) Scilab function written 
> in java or what?
Bingo, this one.


> 
> - "buildDoc( ) => Build the documentation to the Java Help format 
> using the default master file"
> What's the difference then with xmltojar()?
xmltojar is calling scripts. We don't want to rely a basic feature on
system scripts. 

> Adding something like buildDoc("myxmlfile.xml","format") and 
> variations would be most useful IMO. I really think it should be part 
> of SEP #3.
Pierre told me the same thing. 
Seems I have to extend my SEP to this point too but I don't see exactly
how I could extend the buildDoc function.

S