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

[François Vogel]

Hi all,

Welcome to this SEP!
Clarifying and simplifying the way the new help system should be built 
is definitely a good idea, at least it would help me.


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?
How is it supposed to work right 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.

For reference, see also a number of tries of mine here:
http://bugzilla.scilab.org/show_bug.cgi?id=3015#c4


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?

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


- "sh and DOS scripts (SCI/modules/helptools/bin/*) are calling Java 
object with arguments as arguments."

?? arguments as arguments? I don't understand.


- "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?
Sorry, I don't understand what you're proposing.


- "buildDoc( ) => Build the documentation to the Java Help format 
using the default master file"
What's the difference then with xmltojar()?


- "This feature is too specific and won't be moved as a Scilab 
function (however, some work is needed on this file)"
About what file are you talking about here (this sentence appears 
twice in your SEP, same question)?


A reference implementation, or at least some more details about what 
will be changed into what, and how, would clarify your proposal. Sorry 
I admit frankly that I'm obviously missing the point.


> For now, I am only considering the whole build process for the
> documentation. This could be extended in the future.

Again, I don't understand what's you're point here.

Or perhaps are you talking about the granularity of the commands? I 
mean, previously we had both xmltohtml and xmlfiletohtml.
With the Scilab 5 scheme, how can I build the help file from the xml 
file just for one file? Why do I need to recreate the entire help 
(needs an hour, as said above) when I correct a single character typo 
in one of the thousands xml files?

Adding something like buildDoc("myxmlfile.xml","format") and 
variations would be most useful IMO. I really think it should be part 
of SEP #3.

Francois